diff options
Diffstat (limited to 'po/README')
| -rw-r--r-- | po/README | 118 |
1 files changed, 40 insertions, 78 deletions
@@ -1,34 +1,18 @@ Q: I've added a new source file, how do I make sure it's strings get translated? -A: Edit Makefile.in and add the source file to the appropriate *_POTFILES list. - Then run "make update-po". - - NOTE: Now this i only necessary for python files that lack the .py - extension. All .py, .c and .h files are automatically sourced. - -Q: Untranslated strings and file locations are missing from my .po file. - How do I add them? - -A: make merge-po - Untranslated strings are left out of the files in SCM. The merge-po command - runs msgmerge to add them again. +A: Add the source file to the POTFILES.in list. Then run "make ipa.pot-update". Q: How do I pick up new strings to translate from the source files after the source have been modified? -A: make merge-po +A: make ipa.pot-update This regenerates the pot template file by scanning all the source files. Then the new strings are merged into each .po file from the new pot file. Q: How do I just regenerate the pot template file without regenerating all the .po files? -A: make update-pot - -Q: I am done translating. How do I commit my changes? - -A: Run `make strip-po` to remove unneeded information from the po files, then - add your changes to SCM. +A: make ipa.pot-update Q: How do I add a new language for translation? @@ -51,13 +35,15 @@ A: The files Makefile.in, LINGUAS control the build, they must be in the SCM. Be careful, .po files may be automatically updated when the source files change (or the .pot changes, usually the .pot file changes only as a result of rescanning the source files). This mean a .po file might be automatically - updated while a translator has the file out for editing, all the caveats - about SCM merging apply. + updated while a file from translation service is being downloaded. + + If there is a conflict, you should generate new pot file, + upload it do the translation service, and re-download the po files. Q: Which are automatically generated and thus do not need to be in SCM? -A: The *.mo files are automatically generated on demand from their corresponding - .po file. +A: The *.gmo files are automatically generated on demand from their + corresponding .po file. Q: What role does the .pot file play? @@ -65,79 +51,55 @@ A: The .pot file is called a template file. It is generated by scanning all the source files (e.g. *.py *.c *.h) in the project using xgettext. xgettext locates every translatable string (e.g. strings marked with _()) and adds that string along with metadata about it's location to the .pot file. Thus - the .pot file is a collection of every translatable string in the project. If - you edit a source file and add a translatable string you will have to + the .pot file is a collection of every translatable string in the project. + If you edit a source file and add a translatable string you will have to regenerate the .pot file in order to pick up the new string. + This template file needs to be uploaded from time to time to translation + service so translators can translate new and updated strings incrementally. Q: What is the relationship between a .po file and the .pot file? -A: A .po file contains the translations for particular language. It derives from - the .pot file. When the .pot file is updated with new strings to translate - each .po will merge the new strings in. The .po file is where translators - work providing translations for their language. Thus it's important the .po - not be recreated from scratch and is kept in SCM, otherwise the translators - work will be lost. +A: A .po file contains the translations for particular language. It derives + from the .pot file. When the .pot file is updated with new strings + to translate each .po will merge the new strings in. + Previously the .po file was where translators worked providing translations + for their language. + Today the work is done inside translation service Zanata so the .po files + are kept in SCM just for the case of failure in the translation service. +Q: What is the transation workflow? Let's use an example for French, it's .po file will be fr.po. 1) Developer creates main.c with one translatable sting _("Begin"). - 2) Produce the .pot file by running xgettext on main.c + 2) Maintainer produces the .pot file by running make ipa.pot-update. - 3) .pot file contains one msgid, "Begin" + 3) .pot file contains one msgid, "Begin". - 4) fr.po is created from the .pot file, it also contains one msgid, "Begin" + 4) Maintainer uploads .pot file is to Zanata translation service: + $ zanata-cli push + (all the parameters are taken from zanata.xml file) - 5) Translator edits fr.po and provide the French translation of "Begin". + 5) Translator uses Zanata service to provide the French translation + of "Begin". - 6) Developer adds new translatable sting _("End") to main.c + 5) Maintainer download fr.po is generated by Zanata service, + it also contains one msgid, "Begin". + $ zanata-cli pull - 7) Generate a new .pot file by running xgettext on main.c + 6) Maintainer strips untranslated strings from .po files + to make diffs smaller: + $ make strip-po - 8) .pot file contains two msgid's, "Begin", and "End" + 7) Maintainer commits new .po files to Git. - 9) fr.po is missing the new msgid in the .pot file, so the .pot is merged - into fr.po by running msgmerge. This copies into fr.po the new "End" msgid - but preserves the existing translations in fr.po (e.g. "Begin"). The fr.po - will now have 2 msgid's one which is translated already (e.g. "Begin") and - one that untranslated (e.g. "End"). +Q: What are .gmo files? - 10) Sometime later the French translator comes back to see if he/she needs to - add more translations to fr.po. They see there is a missing translation, - they check fr.po out from SCM, add the missing translation, and then - check fr.po back into SCM. - - This means at any given moment the set of .po files will have varying degrees - of translation completeness. Because the .po files are merged when the source - code files are updated existing translations are not lost. It also means a - .po file which was fully translated may need new translations after a .pot - update. It is permissible to have incomplete translations in a message - catalog, at run time if a translation for a particular string is available in - the message catalog the user will be presented with the string in their - language. However if the string is not yet translated in the .po file then - they just get the original string (typically in English). - -Q: What are .mo files? - -A: .mo files are the content of a .po file but in "machine" format for fast +A: .gmo files are the content of a .po file but in "machine" format for fast run time access (mo = Machine Object, po = Portable Object). .mo files are what gets installed along with the package. Think of a .po as a source file which is compiled into a object file for run time use. -Q: Why don't we use gettexize and autopoint? - -A: Because the framework they produce is too limited. Specifically there is no - way to pass the source language to xgettext when it scans a file. xgettext - only knows how to automatically determine the language from the source files - extension. However we have many files without extensions, thus we have to - group all Python (et. al.) files together and run xgettext on every file *we* - know to Python (because xgettext can't figure this out itself if there is no - file extension). There is another added benefit of avoiding gettextize and - autopoint, simplicity. Managing translations is complex and hard enough as it - is, gettextize and autopoint adds another whole layer of complexity which - just further obscures things. - -Q: Who created the awful mess and who do I ask when things don't work as I - expect or I have further questions? - -A: John Dennis <jdennis@redhat.com> +Credits: +- GNU project +- John Dennis <jdennis@redhat.com> for his work on the original system |