From b8a8575d174e9194358c420c82ee4e3a50d0c637 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Fri, 17 Jan 2014 11:11:42 -0500 Subject: [PATCH] Further edits --- docs/en_us/developers/source/i18n.rst | 151 +++++++++++++++----------- 1 file changed, 89 insertions(+), 62 deletions(-) diff --git a/docs/en_us/developers/source/i18n.rst b/docs/en_us/developers/source/i18n.rst index b19b8e6117..2a825c3b09 100644 --- a/docs/en_us/developers/source/i18n.rst +++ b/docs/en_us/developers/source/i18n.rst @@ -27,15 +27,17 @@ unfortunately limits what you can do with strings in the code. In general: runtime, there is no way for the translator to construct a proper sentence in their language. -2. Do not join together strings at runtime to create sentences. +2. Don't join strings together at runtime to create sentences. 3. Limit the amount of text in strings that is not presented to the user. HTML markup is better applied after the translation. If you give HTML to the translators, there's a good chance they will translate your tags or attributes. -See the detailed :ref:`Style Guidelines ` at the end for -details. +4. Use placeholders with descriptive names: ``"Welcome {student_name}"`` is + much better than ``"Welcome {0}"``. + +See the detailed Style Guidelines at the end for details. Editing source files @@ -77,14 +79,19 @@ XModules, Inputtypes and Responsetypes forbid importing Django. Each of these has its own way of accessing translations. You'll use lines like these instead:: - # for XBlock & XModule: + ### for XBlock & XModule: _ = self.runtime.service(self, "i18n").ugettext + # Translators: a greeting to newly-registered students. message = _("Welcome!") # for InputType and ResponseType: _ = self.capa_system.i18n.ugettext + # Translators: a greeting to newly-registered students. message = _("Welcome!") +"Translators" comments will work in these places too, so don't be shy about +providing clarifying comments to the translators. + Django template files ===================== @@ -105,7 +112,7 @@ Mako template files In Mako template files (`templates/*.html`), you can use all of the tools available to python programmers. Just make sure to import the relevant -functions first. Here's a mako template example:: +functions first. Here's a Mako template example:: <%! from django.utils.translation import ugettext as _ %> @@ -172,11 +179,11 @@ Other kinds of code We have not yet established guidelines for internationalizing the following. -* course content (such as subtitles for videos) +* Course content (such as subtitles for videos) -* documentation (written for Sphinx as .rst files) +* Documentation (written for Sphinx as .rst files) -* client-side templates written using Underscore. +* Client-side templates written using Underscore. Building and testing your code @@ -186,32 +193,16 @@ These instructions assume you are a developer writing new code to check in to Github. For other use cases in the translation life cycle (such as translating the strings, or checking the translations into Github, see use cases). -1. Run the rake i18n:extract command to create human-readable .po files. This - command may take a minute or two to complete: +1. Create human-readable .po files with the latest strings. This command may + take a minute or two to complete:: -:: + $ cd edx-platform + $ rake assets + $ rake i18n:extract - $ cd edx-platform - $ rake i18n:extract - -2. Generate dummy strings: run rake i18n:dummy to create fake translations. See - coverage testing (below) for more details. - - a. By default, these are created in the Esperanto language directory. - - 1. This will blow away any actual Esperanto translation files that may be - there. You can revert to the Github head after you complete testing. - - 2. You will need to switch your browser to Esperanto in order to view - the dummy text. - - 3. Django's implementation requires us to use a real language (like - Esperanto..) rather than an invented language (like Esperanto.. - er Martian) for this testing. - - b. Do not check the dummy text in to Github (in conf/locale/eo/LC_MESSAGES). - -:: +2. Generate dummy strings: See coverage testing (below) for more details. This + will create an "Esperanto" translation that is actually over-accented + English. Use this to create fake translations:: $ rake i18n:dummy @@ -219,26 +210,26 @@ the strings, or checking the translations into Github, see use cases). $ rake i18n:generate -4. Django should be ready to go. The next time you run studio or lms with a - non-English browser, the non-English strings (from step 3, above) should be - displayed. (But be sure that your settings for USE_I18N and USE_L10N are - both set to True. USE_I18N is currently set to False by default in - common.py, but is set to True in lms/envs/dev.py and cms/envs/dev.py) +4. Django should be ready to go. The next time you run Studio or LMS with a + browser set to Esperanto, the accented-English strings (from step 3, above) + should be displayed. Be sure that your settings for ``USE_I18N`` and + ``USE_L10N`` are both set to True. ``USE_I18N`` is set to False by default + in common.py, but is set to True in development settings files. 5. With your browser set to Esperanto, review the pages affected by your code and verify that you see fake translations. If you see plain English instead, your code is not being properly translated. Review the steps in editing - source files (above) + source files (above). Coverage testing **************** This tool is used during the bootstrap phase, when presumably (1) there is a -lot of EdX source code to be converted, and (2) there are not a lot of -available translations for externalized EdX strings. At the end of the +lot of edX source code to be converted, and (2) there are not a lot of +available translations for externalized edX strings. At the end of the bootstrap phase, we will eventually deprecate this tool in favor of other -processes. Once most of the EdX source code has been successfully converted, +processes. Once most of the edX source code has been successfully converted, and there are several full translations available, it will be easier to detect and correct specific gaps in compliance. @@ -273,13 +264,12 @@ This dummy text is also distinguished by Lorem ipsum text at the end of each string, and is always terminated with "#". The original English string is padded by about 30% extra characters, to simulate some language (like German) which tend to have longer strings than English. If you see problems with your -page layout, such as columns that do not fit, or text that is truncated (the # -character should always be displayed on every string), then you will probably -need to fix the page layouts accordingly to accommodate the longer strings. +page layout, such as columns that don't fit, or text that is truncated (the +``#`` character should always be displayed on every string), then you will +probably need to fix the page layouts accordingly to accommodate the longer +strings. -.. _style_guidelines: - Style guidelines **************** @@ -288,7 +278,7 @@ Don't append strings, interpolate values It is harder for translators to provide reasonable translations of small sentence fragments. If your code appends sentence fragments, even if it seems -to work ok for English, the same concatenation is very unlikely to work +to work OK for English, the same concatenation is very unlikely to work properly for other languages. Bad:: @@ -301,34 +291,36 @@ directory has." In some languages the fragments will be in different order. For example, in Japanese, "files" will come before "has." It is much easier for a translator to figure out how to translate the entire -sentence, using the pattern "The directory has %d files." +sentence, using the pattern "The directory has {file_count} files." Good:: - message = _("The directory has %d files.") % len(directory.files) + message = _("The directory has {file_count} files.").format(file_count=directory.files) -Use named interpolation fields -============================== +Use named placeholders +====================== -Named fields are better, especially if there are multiple fields, or if some -fields will be locally formatted (for example, number, date, or currency). +Python string formatting provides both positional and named placeholders. Use +named placeholders, never use positional placeholders. Positional placeholders +can't be translated into other languages which may need to re-order them to +make syntactically correct sentences. Even with a single placeholder, a named +placeholder provides more context to the translator. Bad:: message = _('Today is %s %d.') % (m, d) -Good:: +OK:: message = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d} -Better:: +Best:: message = _('Today is {month} {day}.').format(month=m, day=d) Notice that in English, the month comes first, but in Spanish the day comes -first. This is reflected in the -edx-platform/conf/locale/es/LC_MESSAGES/django.po file like this:: +first. This is reflected in the .po file like this:: # fragment from edx-platform/conf/locale/es/LC_MESSAGES/django.po msgid "Today is {month} {day}." @@ -390,6 +382,41 @@ The difference between the right way and the wrong way can be very subtle: message = _("Goodbye.") +Be aware of nested syntax +========================= + +When translating strings in templated files, you have to be careful of nested +syntax. For example, consider this Javascript fragment in a Mako template:: + + + +When rendered for a French speaker, it will produce this:: + + + +which is now invalid Javascript. This can be avoided by using double-quotes +for the Javascript string. The better solution is to use a filtering function +that properly escapes the string for Javascript use:: + + + +which produces:: + + + +Other places that might be problematic are HTML attributes:: + + ${_("I love you.")} + + Singular vs plural ================== @@ -399,22 +426,22 @@ count:: if count == 1: msg = _("There is 1 file.") else: - msg = _("There are %d files.") % count + msg = _("There are {file_count} files.").format(file_count=count) This is not the correct way to choose a string, because other languages have -different rules for when to use singluar and when plural, and there may be more +different rules for when to use singular and when plural, and there may be more than two choices! One option is not to use different text for different counts:: - msg = _("Number of files: %d") % count + msg = _("Number of files: {file_count}").format(file_count=count) If you want to choose based on number, you need to use another gettext variant to do it:: from django.utils.translation import ungettext - msg = ungettext("There is %d file", "There are %d files", count) - msg = msg % count + msg = ungettext("There is {file_count} file", "There are {file_count} files", count) + msg = msg.format(file_count=count) This will properly use count to find a correct string in the translation file, and then you can use that string to format in the count.