Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
help_with_translation [2021/10/05 08:12] – added info about editing English strings (I highly recommend that no-one ever actually do this) atarihelp_with_translation [2023/02/09 02:41] (current) – cleanup/correction atari
Line 3: Line 3:
 Batocera comes in a variety of local languages, and relies on the community to help with the translations. We need you for this! Batocera comes in a variety of local languages, and relies on the community to help with the translations. We need you for this!
  
-===== How can I help? =====+===== For translators =====
  
-==== Translate for a new language ====+  - First check if someone has already started a translation on [[http://translations.batocera.org/|the translations page]]. Download the two ''*.pot'' files for your language you are going to add translations for. The two files are for EmulationStation-specific strings (ES file) and system-specific options (Options file). If starting a new language, download the ''*.pot'' files from the ''new language'' row in the table. 
 +  - Edit and then compile your translation files. You can use the [[https://poedit.net/|Poedit program]] on your desktop, or online with the [[https://localise.biz/free/poeditor|Poeditor tool]] to create the ''*.po'' and ''emulationstation2.mo'' files specific to your language.<WRAP center round important> 
 +If using a plain text editor to make your modifications instead, make sure it keeps the Unix end-of-line terminators. 
 +</WRAP> 
 +  - [[#test_the_translation|Test your translation]] to ensure no lines are cut-off in the UI, special characters appear as intended and most importantly that Batocera does not crash. 
 +  - Once you're happy with your translation, on the translation page click the region code of your language in the "Code" column and then upload the file to the appropriate "ES file" or "Options file" column on the right side. \\ {{:translation_steps.png|Screenshot showing the step order of clicks, from left to right, top to bottom.}}<WRAP center round tip> 
 +If it's a brand new language, please contact the dev team on the [[https://discord.gg/ndyUKA5|#translations-files channel of our Discord server]] to get your language added to the table. 
 +</WRAP>
  
-  - See what is the current status of your language. You can [[https://mirrors.o2switch.fr/batocera/x86_64/stable/last/|check on this page]] to see what's the % of strings that are currently translated for each supported language in the latest stable version of Batocera. +Thank you so much for your help!
-  - Download the current translation file [[https://github.com/batocera-linux/batocera-emulationstation/tree/master/locale/lang|from this directory]]. It's an ''emulationstation.po'' text file with all the strings to be translated. +
-  - Compile your ''emulationstation2.po'' file into ''emulationstation2.mo''. You can use the [[https://poedit.net/|Poedit program]] on your desktop, or online with the [[https://localise.biz/free/poeditor|Poeditor tool]]. +
-  - Connect to your [[access_the_batocera_via_ssh|batocera through SSH]]. +
-  - Copy your ''emulationstation2.mo'' file to ''/usr/share/locale/{your_language_code}/LC_MESSAGES/'' -- for instance ''/usr/share/locale/pt_BR/LC_MESSAGES/emulationstation2.mo'' for Brazilian Portuguese. +
-  - Open the command console (SSH terminal) and execute the command ''batocera-save-overlay'' to keep your changes upon reboot. +
-  - Restart your Batocera. +
-  - Once you're happy with your translation, you can submit a PR via Github, or send your .po file back to the dev team on the [[https://discord.gg/ndyUKA5|#translations channel of our Discord server]].+
  
-==== Translate missing strings for an already existing translation ====+<WRAP center round tip> 
 +    * To see a list of the list of missing strings to be translated with their respective line numbers, click on the number in the **ES missing** and **Options missing** columns respectively. 
 +    * If you see a "timer" icon after the file, it means that someone just uploaded a new translation file that hasn't been merged into GitHub yet. 
 +</WRAP>
  
-  - Open the ''/usr/share/locale/{your_language_code}/LC_MESSAGES/emulationstation2.po'' file for your chosen language with either POEdit or an ordinary text editor like Notepad++. +==== Test your translation ====
-  - Make your translation edits and save the file, then run ''batocera-save-overlay'' from SSH/terminal to keep them after rebooting. +
-  - Get your ''.po'' file and put it into the #translations channel on our Discord server. +
-  - That's it.+
  
-Thank you for your help!+  - Merge the ''emulationstation2.po'' and ''batocera-es-system.po'' files in your preferred editor and export the ''emulationstation2.mo'' file from it. 
 +  - Connect to Batocera via [[:winscp|WinSCP]] (or [[:access_the_batocera_via_ssh|via SSH]]). 
 +  - Copy your ''emulationstation2.mo'' file to ''/usr/share/locale/<your language code>/LC_MESSAGES/'' -- for instance ''/usr/share/locale/pt_BR/LC_MESSAGES/emulationstation2.mo'' for Brazilian Portuguese. 
 +  - On a keyboard connected to the Batocera machine, press ''[Alt]'' + ''[F4]'' (or run ''%%batocera-es-swissknife --restart%%'' if in SSH) to refresh the language strings in ES. 
 +  - Now explore ES to view all the strings you've translated!
  
-===== What if I wanted to edit an English string? =====+To keep your changes persistent between reboots, connect via SSH if you haven't already and run ''batocera-save-overlay'' to save the overlay. 
 + 
 +===== For developers ===== 
 + 
 +==== Manually add in a line to be translated ==== 
 + 
 +If there is a line in EmulationStation that does not have a string entry in the PO file, then it can be manually added in with the fake_gettext library: 
 + 
 +<code> 
 +#define fake_gettext_stringname pgettext("category", "string"
 +</code> 
 + 
 +For example: 
 + 
 +<code> 
 +#define fake_gettext_flatten_glow pgettext("game_options", "FLATTEN-GLOW"
 +</code> 
 + 
 +Place this into the top of the function which contains the untranslated string and upon next compilation it will be added to all the relevant PO files. 
 + 
 +==== Add a comment in the code for translators ==== 
 + 
 +If you are coding something new in Batocera and think that the string to be translated might be a bit ambiguous for translators (remember, they will only see the string in isolation, which might not make sense outside of its context), you can add a comment just for translators to see when they get to that string. In EmulationStation or Batocera's es_features, add the following comment right before the code in which the string appears: 
 + 
 +<code> 
 +/* TRANSLATION: Short comment that explains the context of the string. */ 
 +</code> 
 + 
 +For example, this is something that has been added to ''batocera-emulationstation/es-app/src/guis'' in the source code: 
 + 
 +{{:translation_string_example.png|An example of a translator comment in the code.}} 
 + 
 +==== Blacklisted words ==== 
 + 
 +What if you want to add in a string that's explicitly not meant to be translated, such as a proper noun, technical code string or the model name of a retro system? 
 + 
 +Most of these kinds of strings should be automatically picked up and removed by the ''createEsTranslations'' function in [[https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/batocera-es-system.py]], however there might come a case where a word fails to fall into one of its filters. 
 + 
 +Such words can be manually appended to https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/locales/blacklisted-words.txt in the source code. Just add the word on a new line, simple as that. 
 + 
 +==== What if I wanted to edit an English string? ====
  
 Generally editing already-existing English strings in the CPP files is discouraged, as it will remove the translation that was made for it (if it exists). However, there may be times when the English string is misspelled or just plain incorrect and needs to be amended, despite it already being translated. Generally editing already-existing English strings in the CPP files is discouraged, as it will remove the translation that was made for it (if it exists). However, there may be times when the English string is misspelled or just plain incorrect and needs to be amended, despite it already being translated.
Line 32: Line 76:
  
 Understandably, this is a lot of work, especially with how many languages Batocera supports. So here's a mini-tutorial on how to automate the process (on Windows): Understandably, this is a lot of work, especially with how many languages Batocera supports. So here's a mini-tutorial on how to automate the process (on Windows):
 +
 +<WRAP center round alert>
 +This method does cause corruption when re-imported back into POEdit, so double check that first before re-merging.
 +</WRAP>
  
   - Download and install the [[http://findandreplace.io/download|Find and Replace tool]] and [[http://notepad-plus-plus.org/downloads/|Notepad++]].   - Download and install the [[http://findandreplace.io/download|Find and Replace tool]] and [[http://notepad-plus-plus.org/downloads/|Notepad++]].
  • help_with_translation.1633414334.txt.gz
  • Last modified: 3 years ago
  • by atari