Merge branch 'master' of https://github.com/mu-editor/mu

# Conflicts:
#	mu/locale/ja/LC_MESSAGES/mu.po

Makefile

@@ -15,8 +15,9 @@ all:
 	@echo "make publish-test - publish the project to PyPI test instance."
 	@echo "make publish-live - publish the project to PyPI production."
 	@echo "make docs - run sphinx to create project documentation."
-	@echo "make translate - create a messages.pot file for translations."
-	@echo "make translateall - as with translate but for all API strings."
+	@echo "make translate_begin LANG=xx_XX - create/update a mu.po file for translation."
+	@echo "make translate_done LANG=xx_XX - compile translation strings in mu.po to mu.mo file."
+	@echo "make translate_test LANG=xx_XX - run translate_done and launch Mu in the given LANG."
 	@echo "make win32 - create a 32bit Windows installer for Mu."
 	@echo "make win64 - create a 64bit Windows installer for Mu."
 	@echo "make macos - create a macOS native application for Mu."
@@ -38,6 +39,7 @@ clean:
 	find . \( -name '*.bak' -o -name dropin.cache \) -delete
 	find . \( -name '*.tgz' -o -name dropin.cache \) -delete
 	find . | grep -E "(__pycache__)" | xargs rm -rf
+	rm -f ./mu/locale/messages.pot
 
 run: clean
 ifeq ($(VIRTUAL_ENV),)
@@ -83,15 +85,14 @@ docs: clean
 	@echo file://`pwd`/docs/_build/html/index.html
 	@echo "\n"
 
-translate:
-	find . \( -name _build -o -name var -o -path ./docs -o -path ./mu/contrib -o -path ./utils -o -path ./mu/modes/api \) -type d -prune -o -name '*.py' -print0 | $(XARGS) pygettext
-	@echo "\nNew messages.pot file created."
-	@echo "Remember to update the translation strings found in the locale directory."
+translate_begin:
+	@python make.py translate_begin LANG=$(LANG)
 
-translateall:
-	pygettext mu/* mu/debugger/* mu/modes/* mu/resources/*
-	@echo "\nNew messages.pot file created."
-	@echo "Remember to update the translation strings found in the locale directory."
+translate_done:
+	@python make.py translate_done LANG=$(LANG)
+
+translate_test:
+	@python make.py translate_test LANG=$(LANG)
 
 win32: check
 	@echo "\nBuilding 32bit Windows MSI installer."

docs/setup.rst

@@ -30,6 +30,7 @@ into your virtualenv with::
 
     * ``[tests]`` specifies the testing dependencies, needed by ``make test``.
     * ``[docs]`` specifies the doc building dependencies, needed by ``make docs``.
+    * ``[i18n]`` specifies the translation dependencies, needed by ``make translate_*``.
     * ``[package]`` specifies the packaging dependencies needed by ``make win32``,
       ``make win64``, ``make macos``, or ``make dist``.
 

docs/translations.rst

@@ -8,147 +8,92 @@ simple and there exist plenty of tools to help you.
 You can contribute in three ways:
 
 * Improve or extend an existing translation.
-* Create a completely new translation for a new locale.
+* Create a completely new translation for a new language.
 * Make a translation of `Mu's website <https://codewith.mu/>`_ (see the
   :doc:`website` guide for how to do this).
 
 In both cases you'll be using assets found in the ``mu/locale`` directory.
 
 Mu uses Python's standard `gettext <https://docs.python.org/3.6/library/i18n.html>`_
 based internationalization API so we can make use of standard tools to help
-translators, such as `poedit <https://poedit.net/>`_.
+translators, such as `babel <https://babel.pocoo.org/en/latest/>`_ or
+`Poedit <https://poedit.net/>`_.
 
-.. note::
+.. admonition:: Non-techincal users
 
-    You may need to run ``make translate`` as part of this process. This, in
-    turn, depends on the presence of the ``pygettext.py`` command on your
-    system. The ``pygettext.py`` command should come installed as part of the
-    Python language, but some operating systems don't include it by default. 
-    For example, to install ``pygettext.py`` on Fedora you must make
-    sure the ``python3-tools`` package is installed.
+    If you are not a technical user and you are not familiar with the
+    tools and jargon we use in this guide,
+    please reach out to us by
+    `creating a new issue in GitHub <https://github.com/mu-editor/mu/issues/new>`_.
 
-There are currently two possible ways to
-manually change the locale Mu uses for translation strings:
+    We will help you setup user-friendly tool that you can use to contribute
+    new or improved translations,
+    and integrate them into the next Mu release.
 
-* Setting the ``LANG`` the environment variable.
-* Temporarily editing ``mu/__init__.py``.
+    We welcome translations from all users!
 
-The first one is recommended: when using Linux, Raspbian, or macOS, launch Mu with::
 
-    $ LANG=<language> mu-editor
 
-When using Windows, two steps are needed::
+How To
+------
 
-    $ set LANG=<language>
-    $ mu-editor
+Updating or creating a new translation for Mu's user interface requires
+:doc:`setting up a development environment <setup>` beforehand and,
+from there,
+is a four-step process:
 
-The alternative is editing ``mu/__init__.py`` and forcing a specific locale. Look for the following lines of code around the top of the file::
 
-    # Configure locale and language
-    # Define where the translation assets are to be found.
-    localedir = os.path.abspath(os.path.join(os.path.dirname(__file__), 'locale'))
-    language_code = QLocale.system().name()
-    # DEBUG/TRANSLATE: override the language code here (e.g. to Chinese).
-    # language_code = 'zh'
-    gettext.translation('mu', localedir=localedir,
-                        languages=[language_code], fallback=True).install()
+1. Produce an up to date ``mu.po`` file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Open a CLI shell,
+change the working directory to Mu's repository root,
+and run::
 
-As the comment suggests, temporarily uncomment and set ``language_code`` to the target
-``<language>`` for translation, make your changes, as explained below, and re-run
-Mu to check your updates are correct and appropriate for your target locale.
+    $ make translate_begin LANG=xx_XX
 
+Where ``xx_XX`` is the identifier for the target language.
 
-.. note::
+This creates (or updates, if it already exists) the ``mu.po`` file under the
+``mu/locale/xx_XX/LC_MESSAGES/`` directory --
+this is where the original British English messages
+are associated with their localized translations.
 
-    In either case, ``<language>`` should be one of the supported locales,
-    including the ones in development, per the directory names found under
-    ``mu/locale`` (examples: ``de_DE``, ``es``, ``fr``, ``ja``, etc.).
 
-    When an unknown value is set, Mu falls back to its native British English UI.
+2. Translate Mu user interface strings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    A language-only specification, like ``de`` or ``pt``,
-    uses one of the more specific language / country code locales,
-    like ``de_DE`` for ``de``, or one of ``pt_BR`` / ``pt_PT`` for ``pt``.
+Use a tool of your choice to edit the ``mu.po`` file:
 
+* Those looking for a GUI based tool can try out `Poedit <https://poedit.net>`__.
+* Others might prefer a plain text editor, which will be sufficient.
 
-Improve an Existing Translation
--------------------------------
 
-If you want to improve or extend an existing translation you should edit a file
-called ``mu.po`` for the target locale. Such files for existing translations
-are found in the ``mu/locale/<LOCALE>/LC_MESSAGES`` directory (remember to
-replace ``<LOCALE>`` with the value for the locale's language / country code
-combination `as specified by gettext convention <https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html>`_).
+3. Check the translation result
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Open the ``mu.po`` file in an editor or translation tool of your choice (we
-recommend `poedit <https://poedit.net/>`_ as a great solution for this). If
-you're using a plain text editor, remember to make your changes to the message
-string (``msgstr``) *not* the message id (``msgid``). 
+As you progress,
+check the translation results by launching Mu with::
 
-Once you've saved and, most importantly, **checked your translation strings
-appear as expected in Mu**, commit your changes and create a pull request via
-GitHub. Alternatively, if you're not a technical user,
-`create a new issue in GitHub <https://github.com/mu-editor/mu/issues/new>`_
-and attach your ``mu.po`` file along with details of the locale.
+    $ make translate_test LANG=xx_XX
 
+As before,
+``xx_XX`` is the identifier for the target language.
 
-Create a New Translation
-------------------------
+When done checking,
+quit Mu,
+and go back to step 2. as many times as needed.
 
-There are three steps to creating a new translation:
 
-1. [Optional] Use ``make translate`` to create an up-to-date ``messages.pot`` file.
-2. Use a tool like `poedit <https://poedit.net/>`_ to load the ``messages.pot`` file, select a language / locale and create appropriately translated messages.
-3. Save the resulting ``mu.po`` file into the ``mu/locale/<LOCALE>/LC_MESSAGES`` directory, replacing ``<LOCALE>`` with the value for the locale's language / country code combination `as specified by gettext convention <https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html>`_.
+4. Submit your translation work
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Taking each in turn, you may (optionally) need to create an up-to-date
-specification of all the strings found within Mu that need translating. This is
-the ``messages.pot`` file and you simple need to issue the following command
-to regenerate it::
+This process produced two new or updated files,
+both under the ``mu/locale/xx_XX/LC_MESSAGES/`` directory:
 
-    $ make translate
+* ``mu.po`` containing the text based source of the translation strings.
+* ``mu.mo`` containing a compiled version of the above, used by Mu at runtime.
 
-You'll see some output ending with the message::
+Commit your changes and create a pull request via GitHub.
 
-    New messages.pot file created.
-    Remember to update the translation strings found in the locale directory.
-
-To create a new translation you'll need to use a tool such as
-`poedit <https://poedit.net/>`_ to load the ``messages.pot`` and configure
-output for a new locale. The resulting output is a ``mu.po`` file that needs
-to be saved in the ``mu/locale/<LOCALE>/LC_MESSAGES`` directory, replacing
-``<LOCALE>`` with the value for the new locale's language / country code
-combination
-`as specified by gettext convention <https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html>`_.
-
-This process is illustrated below, with the cross-platform and open-source
-`poedit <https://poedit.net/>`_ tool.
-
-Create New Translation
-++++++++++++++++++++++
-
-.. image:: po1.png
-
-Select ``messages.pot``
-+++++++++++++++++++++++
-
-.. image:: po2.png
-
-Specify the New Locale
-++++++++++++++++++++++
-
-.. image:: po3.png
-
-At this point, simply use `poedit <https://poedit.net/>`_ to fill in the
-translated messages from the source messages.
-
-Save ``mu.po`` when Finished
-++++++++++++++++++++++++++++
-
-.. note::
-
-    Please make sure you check your translation is appropriate and correct for
-    your target before submitting your work.
-
-.. image:: po4.png
+Thanks!