1. Forum moved (you can use login and pass from old forum)
  2. Many discussions moved to the bugtracker

How Translations Work

Discussion in 'Translations' started by pmprog, Aug 27, 2014.

  1. pmprog

    pmprog Well-Known Member Official Developer Administrator

    Joined:
    Jul 8, 2014
    Messages:
    175
    Likes Received:
    12
    Best Answers:
    0
    (EDIT by JonnyH)
    This is now outdated, see below for the 'new' transifex-based translation mechanism

    (Original message)

    Translating OpenApoc can be done one of two ways.

    Firstly, when completed, you'll be able to use the OpenApoc.Toolset. This will provide you a simple GUI for editing all the data related to the game, from languages, their translations, to the GUI layout and images.

    Secondly, you can just edit the XML files. You need to save your changes in UTF-8 format, and you must XML-encode special characters (such as <, >, and ')

    Languages are defined like this:
    Code:
    <openapoc>
     <language id="gb_en">English</language>
    </openapoc>
    
    Strings are then defined like this:
    Code:
    <openapoc>
     <string id="STR_HELLO">
      <gb_en>Hello</gb_en>
      <es_la>Hola</es_la>
     </string>
    </openapoc>
    
    Translations do not require to be next together. So you can seperate languages if you wish:
    Code:
    --------------------------------------------- english.xml
    <openapoc>
     <string id="STR_HELLO">
      <en_gb>Hello</en_gb>
     </string>
    </openapoc>
    
    --------------------------------------------- spanish.xml
    <openapoc>
     <string id="STR_HELLO">
      <es_la>Hola</es_la>
     </string>
    </openapoc>
    
    As long as the documents are linked in the include list of the game definition, they will be accessible in-game
     
  2. Skin36

    Skin36 Well-Known Member Official Developer Administrator

    Joined:
    Apr 5, 2015
    Messages:
    65
    Likes Received:
    20
    Best Answers:
    1
  3. JonnyH

    JonnyH Well-Known Member Official Developer Administrator

    Joined:
    Jul 17, 2014
    Messages:
    185
    Likes Received:
    39
    Best Answers:
    0
    Right, a big change to how translations are done:

    We no longer use the 'custom' XML format described above - instead we use gettext .po files (sources from Transifex - see Skin36's comment - the project is at https://www.transifex.com/x-com-apocalypse/apocalypse/ )

    * What does this mean?
    In code, use the UString OpenApoc::tr(const UString &str, const UString domain = "ufo_string"); function (defined in library/strings.h) to get a translated string.
    90% of the time, you'll leave the domain as the default (the only other so far is "paedia_string" - for the ufopaedia) - and you're already in the OpenApoc namespace, so the call becomes simply:
    auto translatedString = tr("Hello World!");

    * The translations
    The 'source' of the translations should be in 'en' - that is 'generic' english (it often ends up meaning 'US' English, just because those damn yanks can't keep it in their pants)

    The two files you should modify if you ever want to add a string are 'data/languages/ufo_string.pot' and 'data/languages/paedia_string.pot' (named after their 'domain').

    ALL THE OTHER .po AND .mo FILES IN THE data/languages/* FOLDERS ARE GENERATED AND SHOULDN'T BE TOUCHED DIRECTLY!

    These .pot files are then used as 'source' translations for transifex. There's already a 'tx' (transifex's command line tool) config in '.tx/config' that sets this up. Effectively it means if you add something to a .pot, push it to transifex with 'tx push -s'.

    When you want to update the translations from transifex, you then do 'tx pull -a'. This pulls down the latest languages-specific .po files.

    Unfortunately, these .po files then need to be formatted into the .mo binary files - to do this you need the 'msgfmt' command from 'gettext' - there's a cmake command that does this (and copies them to the right place) setup with the target 'update-translations', so if you're on Unix it's pretty simple.
    God help you if you're on windows.

    (Note, because of this, adding a new language requires you to add it to the "LANGUAGES" list in CMakeLists.txt, but I doubt that'll be common)
     
  4. Solarius Scorch

    Solarius Scorch Call to Power modder Global Moderator

    Joined:
    Jul 8, 2014
    Messages:
    198
    Likes Received:
    6
    Best Answers:
    0
    Once the product is finished, will we have language files in human readable format (like in OpenXCom)?
     
  5. Skin36

    Skin36 Well-Known Member Official Developer Administrator

    Joined:
    Apr 5, 2015
    Messages:
    65
    Likes Received:
    20
    Best Answers:
    1
    Can I get a text for translation (.PO) from the source of the game?
     
  6. JonnyH

    JonnyH Well-Known Member Official Developer Administrator

    Joined:
    Jul 17, 2014
    Messages:
    185
    Likes Received:
    39
    Best Answers:
    0
    I mentioned this on irc, but I'll put it here for reference:
    - The 'current' source translation files are in git - data/languages/paedia_string.pot and ufo_string.pot
    - These are currently just the files extracted by you from 'original' apoc and put on transifex
    - Because of that, they're not 'complete' and we expect to add more strings (as it's likely we build out strings differently to 'original' apoc, so small translation changes will be necessary, plus any extra strings we add on top of the original)
    - It probably makes sense to merge them into a single .pot file sometime in the future
    - Currently they are manually edited - I intend to be able to auto-generate this, but it's non-trivial as some strings come from our XML, some are in-code (Soon, currently working on a new Rules and GameState serialization that will include this for the xml, and we can use xgettext to extract them from the source and merge the two outputs)

    So, as with most things right now, it's a work in progress :)

    PPS If you realise any strings are missing, add them to the .pot files in git and push a change request on github.

    From that, we can upload the new strings to the transifex project (I hopefully have setup a config for the 'tx' tool from transifex in the git - in a root '.tx' folder)
    Then we can get the strings translated, and pull the latest translation databases from transifex for each language, to the .po files in the data/languages directory, and from them the .mo files that the game actually uses at runtime.

    Effectively, only the .pot files should ever be edited manually, the .po files are then auto-generated by transifex, and the .mo files generated from /those/ using msgfmt (there's a cmake build target to help with that, not yet setup to work automatically on windows though)
     
  7. Skin36

    Skin36 Well-Known Member Official Developer Administrator

    Joined:
    Apr 5, 2015
    Messages:
    65
    Likes Received:
    20
    Best Answers:
    1
    From the transifex removed Ufopaedia file. Now, all the strings are in a single file.
     
  8. Solarius Scorch

    Solarius Scorch Call to Power modder Global Moderator

    Joined:
    Jul 8, 2014
    Messages:
    198
    Likes Received:
    6
    Best Answers:
    0
    Great! The division was pretty arbitrary anyway.
     

Share This Page