1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
Internationalisation of Mu
==========================
A really useful and relatively simple way to contribute to Mu is to translate
the user interface into a different language. The steps to do this are very
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.
* 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/>`_.
.. note::
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.
To manually change the locale Mu uses for translation strings, look in
``mu/__init__.py`` for the following lines of code at the start of the file::
# Configure locale and language
# Define where the translation assets are to be found.
localedir = os.path.join('mu', 'locale')
# Use the operating system's locale.
current_locale, encoding = locale.getdefaultlocale()
# Get the language code.
language_code = current_locale[:2]
# DEBUG/TRANSLATE: override the language code here (e.g. to Spanish).
# language_code = 'es'
gettext.translation('mu', localedir=localedir,
languages=[language_code], fallback=True).install()
As the comment suggests, temporarily update the ``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.
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>`_).
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``).
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.
Create a New Translation
------------------------
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>`_.
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::
$ make translate
You'll see some output ending with the message::
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
|
