[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

3 files changed, 55 insertions, 21 deletions

diff --git a/docs/howto/deployment/wsgi/modwsgi.txt b/docs/howto/deployment/wsgi/modwsgi.txt
index 689effba17..90ca1c0527 100644
--- a/docs/howto/deployment/wsgi/modwsgi.txt
+++ b/docs/howto/deployment/wsgi/modwsgi.txt
@@ -74,6 +74,20 @@ should put in this file, and what else you can add to it.
     or by :ref:`using mod_wsgi daemon mode<daemon-mode>` and ensuring that each
     site runs in its own daemon process.
 
+.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads
+
+    If you get a ``UnicodeEncodeError`` when uploading files with file names
+    that contain non-ASCII characters, make sure Apache is configured to accept
+    non-ASCII file names::
+
+        export LANG='en_US.UTF-8'
+        export LC_ALL='en_US.UTF-8'
+
+    A common location to put this configuration is ``/etc/apache2/envvars``.
+
+    See the :ref:`unicode-files` section of the Unicode reference guide for
+    details.
+
 Using a virtualenv
 ==================
 
@@ -222,24 +236,3 @@ Authenticating against Django's user database from Apache
 Django provides a handler to allow Apache to authenticate users directly
 against Django's authentication backends. See the :doc:`mod_wsgi authentication
 documentation </howto/deployment/wsgi/apache-auth>`.
-
-If you get a UnicodeEncodeError
-===============================
-
-If you're taking advantage of the internationalization features of Django (see
-:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
-ensure that the environment used to start Apache is configured to accept
-non-ASCII file names. If your environment is not correctly configured, you
-will trigger ``UnicodeEncodeError`` exceptions when calling functions like
-the ones in :mod:`os.path` on filenames that contain non-ASCII characters.
-
-To avoid these problems, the environment used to start Apache should contain
-settings analogous to the following::
-
-    export LANG='en_US.UTF-8'
-    export LC_ALL='en_US.UTF-8'
-
-Consult the documentation for your operating system for the appropriate syntax
-and location to put these configuration items; ``/etc/apache2/envvars`` is a
-common location on Unix platforms. Once you have added these statements
-to your environment, restart Apache.
diff --git a/docs/howto/deployment/wsgi/uwsgi.txt b/docs/howto/deployment/wsgi/uwsgi.txt
index 89eb9b5698..932d16817b 100644
--- a/docs/howto/deployment/wsgi/uwsgi.txt
+++ b/docs/howto/deployment/wsgi/uwsgi.txt
@@ -108,6 +108,17 @@ Example ini configuration file usage::
 
     uwsgi --ini uwsgi.ini
 
+.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads
+
+    If you get a ``UnicodeEncodeError`` when uploading files with file names
+    that contain non-ASCII characters, make sure uWSGI is configured to accept
+    non-ASCII file names by adding this to your ``uwsgi.ini``::
+
+        env = LANG='en_US.UTF-8'
+
+    See the :ref:`unicode-files` section of the Unicode reference guide for
+    details.
+
 See the uWSGI docs on `managing the uWSGI process`_ for information on
 starting, stopping and reloading the uWSGI workers.
 
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
 =====