[1.9.x] Fixed #17686, refs #17816 -- Added "Files" section to Unicode topic.

Thanks Fako Berkers for help with the patch.

Backport of 25b912abbe31fa440e702b5273c18cf74e2d6e0b from master

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
index f52076d2f7..399a823b84 100644
--- a/docs/ref/unicode.txt
+++ b/docs/ref/unicode.txt
@@ -358,6 +358,36 @@ A couple of tips to remember when writing your own template tags and filters:
   translation objects into strings. It's easier to work solely with Unicode
   strings at that point.
 
+.. _unicode-files:
+
+Files
+=====
+
+If you intend to allow users to upload files, you must ensure that the
+environment used to run Django is configured to work with non-ASCII file names.
+If your environment isn't configured correctly, you'll encounter
+``UnicodeEncodeError`` exceptions when saving files with file names that
+contain non-ASCII characters.
+
+Filesystem support for UTF-8 file names varies and might depend on the
+environment. Check your current configuration in an interactive Python shell by
+running::
+
+    import sys
+    sys.getfilesystemencoding()
+
+This should output "UTF-8".
+
+The ``LANG`` environment variable is responsible for setting the expected
+encoding on Unix platforms. Consult the documentation for your operating system
+and application server for the appropriate syntax and location to set this
+variable.
+
+In your development environment, you might need to add a setting to your
+``~.bashrc`` analogous to:::
+
+    export LANG="en_US.UTF-8"
+
 Email
 =====