Difference between revisions of "GettextForTranslators"

From The Battle for Wesnoth Wiki
(Change repository links to point to github master)
m (Gettext for translators: In the links to the repo, scroll down a bit (to line 50), so the first lines shown are the translation bit)
(3 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
* wesnoth-editor
 
* wesnoth-editor
 
* wesnoth-lib (contains strings shared by game and editor)
 
* wesnoth-lib (contains strings shared by game and editor)
* plus one text-domain for each campaign. The names of these text-domains are constructed from the word wesnoth and the common abbreviation of the campaign (wesnoth-ei, wesnoth-httt, wesnoth-trow, wesnoth-tb, wesnoth-tsg and wesnoth-utbs).
+
* plus one text-domain for each campaign. The names of these text-domains are constructed from the word wesnoth and the common abbreviation of the campaign (wesnoth-ei, wesnoth-httt, wesnoth-trow, wesnoth-tb, wesnoth-tsg, etc).
  
We will use the Swedish (sv) language and the ''wesnoth'' domain as an example in this page.
+
We will use the Swedish (sv) language and the ''wesnoth-editor'' domain as an example.
 
There are three important files for each text-domain:
 
There are three important files for each text-domain:
* ''wesnoth/wesnoth.pot'' file, which contains all the strings used in the main game (neither editor, nor campaign strings). You can see how a ''.pot'' file looks like in the repository : [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth/wesnoth.pot Current repository version].
+
* ''wesnoth-editor/wesnoth-editor.pot'' file, which is a template containing all the strings used in the domain, but with empty strings instead of a translation. You can see how a ''.pot'' file looks like in the repository : [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/wesnoth-editor.pot#L50 Current repository version].
* ''wesnoth/sv.po'', the file containing the translation, you can see how a ''.po'' file looks like in the repository: [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth/sv.po Current repository version].
+
* ''wesnoth-editor/sv.po'', the file containing the translation, you can see how a ''.po'' file looks like in the repository: [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/sv.po#L50 Current repository version].
* ''{translations_dir}/sv/LC_MESSAGES/wesnoth.gmo'', which is a binary version of <lang>.po that the game will use for efficiency reasons. This is not found in cvs, but is created during compilation of the game.
+
* ''{translations_dir}/sv/LC_MESSAGES/wesnoth-editor.mo'', which is a binary version of <lang>.po that the game will use for efficiency reasons. This is not found in the repo, but is created during compilation of the game.
  
 
The first of these files, we update every once in a while, when there is new or modified text,
 
The first of these files, we update every once in a while, when there is new or modified text,
Line 18: Line 18:
 
Then, ''msgmerge'' is used to merge this new "state of the game strings" with your current translations, and generate a new, up-to-date, ''sv.po''.
 
Then, ''msgmerge'' is used to merge this new "state of the game strings" with your current translations, and generate a new, up-to-date, ''sv.po''.
  
Then, a tool called ''msgfmt'' is called, which generates a new ''wesnoth.gmo'' file from your ''wesnoth.po'' file, which will be used by the game once installed.
+
Then, a tool called ''msgfmt'' is called, which generates a new ''wesnoth.mo'' file from your ''wesnoth.po'' file, which will be used by the game once installed.
  
 
"make -C po update-po" does these three steps in one pass.
 
"make -C po update-po" does these three steps in one pass.
Line 26: Line 26:
 
translating new strings, checking "fuzzy" entries.
 
translating new strings, checking "fuzzy" entries.
 
We can handle the administrative tasks of updating etc.
 
We can handle the administrative tasks of updating etc.
You really don't need to bother with any of these commands, unless you want to compile gmo files to check in-game.
+
You really don't need to bother with any of these commands, unless you want to compile .mo files to check in-game.
  
 
Ivanovic is now responsible for integrating translations into Wesnoth, with the help of Torangan and ott.
 
Ivanovic is now responsible for integrating translations into Wesnoth, with the help of Torangan and ott.
Line 33: Line 33:
 
When sending po files to a maintainer to be included in the repository, please create a zip or tar.gz/bz2 archive that you attach, rather than cutting and pasting the translations into an email.  The translated strings are
 
When sending po files to a maintainer to be included in the repository, please create a zip or tar.gz/bz2 archive that you attach, rather than cutting and pasting the translations into an email.  The translated strings are
 
very sensitive to formatting and the archive will also help distinguish which file is which when sending more than one po file.
 
very sensitive to formatting and the archive will also help distinguish which file is which when sending more than one po file.
 +
 +
=== Translating UMC add-ons ===
 +
 +
If an add-on contains only .po files instead of .mo files, then Wesnoth (since 1.14) will read the .po files directly. This means that you can check it in-game without needing to compile a .mo file.
  
 
==  FAQ  ==
 
==  FAQ  ==
Line 52: Line 56:
 
   msgid "Prefs section^General"
 
   msgid "Prefs section^General"
 
   msgstr "General"
 
   msgstr "General"
 +
* '''My PO file already has that translated to "Prefs section^General", should it work?'''
 +
** It does, but probably shouldn't. For strings that have no translation, the part before the "^" will be removed. This is also done when the PO's msgstr is exactly the same as the msgid, which will later break if someone makes any change to the text. For example:
 +
  # wrong but seems to work (shows as "Root")
 +
  msgid "filesystem_path_system^Root"
 +
  msgstr "filesystem_path_system^Root"
 +
  # wrong and shows as "filesystem_path_system^Wurzel"
 +
  msgid "filesystem_path_system^Root"
 +
  msgstr "filesystem_path_system^Wurzel"
 
* '''Who can I ask for further information?'''
 
* '''Who can I ask for further information?'''
 
** You can ask Ivanovic, Torangan, ott, Yann or Isaac in IRC (irc.freenode.net, #wesnoth or #wesnoth-dev).
 
** You can ask Ivanovic, Torangan, ott, Yann or Isaac in IRC (irc.freenode.net, #wesnoth or #wesnoth-dev).

Revision as of 17:01, 18 May 2019

Gettext for translators

Wesnoth translation is now divided into several text-domains:

  • wesnoth
  • wesnoth-editor
  • wesnoth-lib (contains strings shared by game and editor)
  • plus one text-domain for each campaign. The names of these text-domains are constructed from the word wesnoth and the common abbreviation of the campaign (wesnoth-ei, wesnoth-httt, wesnoth-trow, wesnoth-tb, wesnoth-tsg, etc).

We will use the Swedish (sv) language and the wesnoth-editor domain as an example. There are three important files for each text-domain:

  • wesnoth-editor/wesnoth-editor.pot file, which is a template containing all the strings used in the domain, but with empty strings instead of a translation. You can see how a .pot file looks like in the repository : Current repository version.
  • wesnoth-editor/sv.po, the file containing the translation, you can see how a .po file looks like in the repository: Current repository version.
  • {translations_dir}/sv/LC_MESSAGES/wesnoth-editor.mo, which is a binary version of <lang>.po that the game will use for efficiency reasons. This is not found in the repo, but is created during compilation of the game.

The first of these files, we update every once in a while, when there is new or modified text, for instance when a new campaign scenario hits the repository.

Then, msgmerge is used to merge this new "state of the game strings" with your current translations, and generate a new, up-to-date, sv.po.

Then, a tool called msgfmt is called, which generates a new wesnoth.mo file from your wesnoth.po file, which will be used by the game once installed.

"make -C po update-po" does these three steps in one pass.

That was for the "Big Picture". But you really just need to be concerned with the po file: translating new strings, checking "fuzzy" entries. We can handle the administrative tasks of updating etc. You really don't need to bother with any of these commands, unless you want to compile .mo files to check in-game.

Ivanovic is now responsible for integrating translations into Wesnoth, with the help of Torangan and ott. You should contact Ivanovic (crazy-ivanovic AT gmx DOT net), and he'll put them in the game.

When sending po files to a maintainer to be included in the repository, please create a zip or tar.gz/bz2 archive that you attach, rather than cutting and pasting the translations into an email. The translated strings are very sensitive to formatting and the archive will also help distinguish which file is which when sending more than one po file.

Translating UMC add-ons

If an add-on contains only .po files instead of .mo files, then Wesnoth (since 1.14) will read the .po files directly. This means that you can check it in-game without needing to compile a .mo file.

FAQ

  • What's a fuzzy string?
    • It's a string calling for translator revision. For example, if an English string gets a small change and you run the msgmerge program, it will mark the translation of that string fuzzy. When we switched to gettext we marked all translations as fuzzy as lots of them were outdated.
  • What are "Plural-forms"?
    • Some languages have different word forms for different numbers of things (for example in English we have "1 thing" but "2 things"). The rules are different for different languages. You can find them here.
  • My language needs a different font to get displayed correctly.
    • Wesnoth uses several different fonts, and the number is likely to grow with the support for new alphabets/writing systems. Right now we are using DejaVuSans (Roman and Cyrillic), FreeSans (Greek), sazanami-gothic (Japanese) and gkai00mp (Chinese). In the wesnoth/sv.po you will find a string containing the currently used fonts. By changing the order of fonts listed, you choose which font is preferred for your translations. A language using Greek letters would for instance translate that string with:
  msgid "DejaVuSans.ttf,FreeSans.ttf,sazanami-gothic.ttf,gkai00mp.ttf"
  msgstr "FreeSans.ttf,DejaVuSans.ttf,sazanami-gothic.ttf,gkai00mp.ttf"

Note that if a certain letter/glyph is not found in the first font listed, the second font will be scanned for it and so on.

  • What should I do to insert a newline in a string?
    • If you want to insert a newline in a string you need to include the pair of characters "". You can use normal newlines as you wish as they don't affect the translation.
  • How do I use ' within a single-quote delimited string when translating text= in help screen texts?
    • Add a backslash before it.
  • What should I do with strings like "Prefs section^General"?
    • There are ambiguous strings which should be translated in a different way depending on where they appear. For example, we have "General" in the preferences as "General preferences" and we can also have "a General". These strings can have different translations for a given language, so we use "context" to solve this. The prefix only tries to give a hint about the string, and should be not translated, for example:
  msgid "Prefs section^General"
  msgstr "General"
  • My PO file already has that translated to "Prefs section^General", should it work?
    • It does, but probably shouldn't. For strings that have no translation, the part before the "^" will be removed. This is also done when the PO's msgstr is exactly the same as the msgid, which will later break if someone makes any change to the text. For example:
  # wrong but seems to work (shows as "Root")
  msgid "filesystem_path_system^Root"
  msgstr "filesystem_path_system^Root"
  # wrong and shows as "filesystem_path_system^Wurzel"
  msgid "filesystem_path_system^Root"
  msgstr "filesystem_path_system^Wurzel"
  • Who can I ask for further information?
    • You can ask Ivanovic, Torangan, ott, Yann or Isaac in IRC (irc.freenode.net, #wesnoth or #wesnoth-dev).

If you don't like IRC, send a mail to crazy-ivanovic AT gmx DOT net, or pm him (ivanovic) at the forum.

  • How do I quickly test PO file changes?
    • When you modify a PO file, run "make update-gmo" in the main po directory to create a new MO file, then run "make install" there to install the new MO file.
    • Then force cache rebuild. This is tricky -- if you only update MO files, the game may use a cached (i.e., old) version letting you wonder why it still displays the old translation. Either change game.cfg modification time, e.g. with "touch /usr/local/share/wesnoth/game.cfg", or delete the corresponding cache[s] in ~/.wesnoth/cache.
  • I don't know what make is and where to get it. Can I still quickly test PO file changes?
    • Yes you can. Fist, you will need to get an editor for .po files like Poedit or Virtaal.
    • Create a temporary folder to put the .mo files in.
    • Poedit automatically creates an .mo file when you save, in Virtaal choose File -> Export.
    • Name your .mo files according to the text domain and put them into your temporary folder, e.g. for wesnoth-lib/<language_code>.po the .mo file will be called wesnoth-lib.mo.
    • Go to the folder your Wesnoth installation is in, e. g. C:\Users\<username>\AppData\Local\Battle for Wesnoth <version number> in Windows 7.
    • Go to the translations folder and check if there is a subfolder for your language code. If there isn't, create one, then in the new subfolder create a folder called LC_MESSAGES.
    • Copy your .mo files to LC_MESSAGES and restart Wesnoth.
  • The .po file in the repository has changed, how do I move over the translations I've made?
    • If your file with additional translations is called old.po and the new file from the repository is called repo.po, create a new file called new.po by doing
  msgmerge -o new.po old.po repo.po

The new file new.po will keep your translations from old.po as well as the new strings from repo.po, but check the result -- some translations will not be possible to move across if the original strings changed, these are kept as comments at the end of the file.

  • How to generate man files from wesnoth-man(current 1.3 trunk) .po files?

To create "real" manpages out of the po files you have to install a prog named "po4a" and run make update-po4a inside the maindir before running make and make install. They are not automatically created out of po files. With that command the files will be created and afterwards installed.

Note: At least 80% of the .po file must be translated for the creation of a man file

  • Why is the diff from the previous version so huge? I have only made a small change to the .po file with poedit.
    • When saving .po file poedit unwraps all strings. Usually, all .po files are wrapped at 80 characters so if you want smaller diffs and less merge conflicts you can execute the following commands each time after editing with poedit:
  msgattrib file.po > file.po1
  mv file.po1 file.po

Tools

There are several tools to work with .po files:

Of course, you can edit po files with any UTF-8 capable text editor, but the tools listed above have great advantages over any text editor regarding .po translation, like going to next fuzzy/untranslated string, searching only in specific fields (msgid, msgstr, comment), ...

See Also