Review: Needs Fixing some suggestions.
Diff comments: > === modified file 'doc/sphinx/source/tutorial.rst' > --- doc/sphinx/source/tutorial.rst 2013-04-03 09:06:34 +0000 > +++ doc/sphinx/source/tutorial.rst 2014-05-29 10:48:20 +0000 > @@ -269,4 +269,62 @@ > coroutines share the same environment and can therefore use global variables > to communicate with each other. > > + > +Preparing Strings for Translation > +--------------------------------- > + > +When writing your scenario's text, it is important to keep in mind that > these will be translated into various languages. This entails that word forms > and word order will change, and some languages have more than one plural > form. So, here are some pointers for good string design. For examples for the > formatting discussed here, have a look at ``maps/MP Scenarios/Island > Hopping.wmf/scripting/multiplayer_init.lua`` in the source code. will -> might? The tutorial is also for scenario maps that can be uploaded to the site - those will never be translated. Maybe open up with something like : "If you want your scenario to be translatable into different languages, keep these things in mind..." > + > + > +Translator Comments > +^^^^^^^^^^^^^^^^^^^ > + > +If you have a string where you feel that translators will need a bit of help > to understand what it does, you can add a translator comment to it. > Translator comments are particularly useful when you are working with > placeholders, because you can tell the translator what the placeholder will > be replaced with. Translator comments need to be inserted into the code in > the line directly above the translation. Each line of a translator comment > has to be prefixed by ``-- TRANSLATORS: ``, like this: > + > +.. code-block:: lua > + > + -- TRANSLATORS: This is just a test string > + -- TRANSLATORS: With a multiline comment > + print _ "Hello Word" -- Will print in German: "Hallo Welt" the _ has not been explained, or has it? Also the -- Will print in German is more confusing than useful imho. > + > + > +Working with Placeholders > +^^^^^^^^^^^^^^^^^^^^^^^^^ > + > +If you have multiple variables in your script that you wish to include > dynamically in the same string, please use ordered placeholders to give > translators control over the word order. We have implemented a special Lua > function for this called ``bformat`` that works just like the > ``boost::format`` function in C++. Example: you can link to the documentation: https://wl.widelands.org/docs/wl/autogen_globals/#string.bformat > + > +.. code-block:: lua > + > + local world = _("world") -- Will print in Gaelic: "saoghal" > + local hello = _("hello") -- Will print in Gaelic: "halò" > + -- TRANSLATORS: %1$s = hello, %2$s = world > + print (_ "The %1$s is '%2$s'"):bformat(hello, world) -- Will print in > Gaelic: "Is 'halò' an saoghal" > + > + > +Numbers in Placeholders > +^^^^^^^^^^^^^^^^^^^^^^^ > + > +Not all languages' number systems work the same as in English. So, mocking > up an example with putting Gaelic grammar on an English word for > illustration, we would have something like `0 boat`, `1 or 2 bhoat`, `3 > boats`, `20 boat`... So, instead of using ``_`` to fetch the translation, any > string containing a placeholder that is a number should be fetched with > ``ngettext`` instead. First, you fetch the correct plural form, using the > number variable and ``ngettext``: I find the example hard to follow. How about using 1 fish, 2 fish compared to 1 fisch, 2 fische? english readers will understand that fish is irregular even in their own lanugage and that it might not be in other languages. > + > +.. code-block:: lua > + > + pretty_plurals_string = ngettext("There is %s world" , "There are %s > worlds", number_of_worlds) > + > + > +Then you still need to format the string with your variable: > + > +.. code-block:: lua > + > + print pretty_plurals_string:format(number_of_worlds) > + > +If you have a string with multiple numbers in it that would trigger plural > forms, split it into separate strings that you can fetch with ``ngettext``. > You can then combine them with ``bformat`` and ordered placeholders. > + > + > +Handling Long Strings > +^^^^^^^^^^^^^^^^^^^^^ > + > +If you have a really long string, check if there is a logical place where > you could split this into two separate strings for translators. It is easier > for translators to translate smaller chunks, and if you should have to change > the string later on, e.g. to fix a typo, you will break less stuff. The > strings will be put into the translation files in the same order as they > appear in the source code, so the context will remain intact for the > translators. - give some idea what a 'really long string' is for you. 80 chars? 120 chars? - break less translations (instead of stuff). > + > +Also, please hide all formatting control characers from our translators. > This includes HTML tags as well as new lines in the code! For an example, > have a look at ``campaigns/atl01.wmf/scripting/texts.lua`` > + > .. vim:ft=rst:spelllang=en:spell > -- https://code.launchpad.net/~widelands-dev/widelands/bug-1324137/+merge/221353 Your team Widelands Developers is subscribed to branch lp:~widelands-dev/widelands/bug-1324137. _______________________________________________ Mailing list: https://launchpad.net/~widelands-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~widelands-dev More help : https://help.launchpad.net/ListHelp
