Difference between revisions of "Information for translators"

Revision as of 10:53, 22 July 2019 (view source) Pr2 (talk | contribs) (→‎What are Fuzzy lines in PoEdit?: Mention that fuzzy or to be reviewed is the same) ← Older edit		Revision as of 11:04, 22 July 2019 (view source) Pr2 (talk | contribs) (→‎FAQ: Remarks about special chars in original strings) Newer edit →
Line 51:		Line 51:
	Remark: I will explain later on how to properly translated plugins (stay tuned).		Remark: I will explain later on how to properly translated plugins (stay tuned).
		+
		+	=== What are %s, %d, %f do I need to keep them? ===
		+
		+	%s, %d, %f, ... are respectively string, number, float number replacement strings, they are used in dynamically created string. So the same numbers of those special characters needs to be in your translation. You also need to keep them "attached" so %s cannot became % s in your translation. So be careful, especially if you trust suggested translation by PoEdit sometimes in the suggested translation those special important characters are changed.
		+
		+	=== What is \n? ===
		+
		+	\n is to force a carriage return so to preserve the layout of OpenPLi you need to respect them too. And there are some original strings that start with a \n this is normal, your translated string must also start with \n.
		+
		+	=== Do I need to respect spaces ===
		+
		+	Yes, some translation start or end with spaces, this is normal since they are part of a longer string so you need to preserve those starting and trailing spaces.
	== PoEdit ==		== PoEdit ==

---

Revision as of 11:04, 22 July 2019

Foreword

OpenPLi is always looking for help to have it translated properly in many languages. But we kindly ask you to translate in your native language or in a language that you are really familiar with. OpenPLi is not looking for automated translation jobs.

The easiest way to translate

1. We recommend that you download and install PoEdit from this site (please consider to register it if you appreciate it): https://poedit.net/
2. Once installed go into: Preferences - Advanced - suppress the wrap line option and do not select preserve original file format
3. Download the language file you want to work on from: https://github.com/OpenPLi/enigma2/tree/develop/po (click on the file name, it will show you the file content, press the RAW button and save it locally on your disk).
4. Open it up with PoEdit
5. You can start translating the file
6. Save it, you will get 2 files xx.po and xx.mo (where xx is your language code)
7. Upload your updated xx.po file to the forum and we will put it back into github for you: https://forums.openpli.org/forum/55-en-enduser-support/ (we don't need to xx.mo file only the xx.po is important for us).

FAQ

How can I test my translation on my OpenPLi?

In order to test you translation work on you receiver, you will need a FTP access to it.
You can get a free FTP client from: https://filezilla-project.org/ (or any FTP client of your choice).

Advice: if you use FileZilla client go into Parameters - Transferts - FTP: file type : set it to Binary (this will avoid you many problems when using FTP).

1. You have a local file that you have worked on called: xx.mo (where xx is your language code) rename it into: enigma2.mo
2. Connect to your receiver and go to this path: /usr/share/enigma2/po
3. There you will see a series of folders, one per language, enter the language that you are working on: /usr/share/enigma2/po/xx/LC_MESSAGES
4. Rename the file already existing on your receiver enigma2.mo into enigma2.bak (this step is important if you want to be able to rollback your changes)
5. Transfert your own enigma2.mo file
6. Restart your receiver
7. Enjoy your translation

My enigma2.mo gives trouble: how to rollback?

1. If you have followed the previous step carefully, connect with FTP to you receiver go back into the folder, delete your enigma2.mo and rename the enigma2.bak into enigma2.mo
   
2. Restart you receiver.

There is a mistake in the original strings that I want to translate, how can I fix it?

If you find a mistake in the original strings / sentences that you need to translate it is useless to try to fix it in the po file. The correction must done in the source code.
So please report the error on the OpenPLi forum and wait to have it fixed into the source code and the po files including the correction to be generated again.
You can continue to translate in between, just skip the erroneous strings.

Do I need to translate every strings?

Some strings, perhaps, doesn't need to be translated, you can of course decide to skip those strings and leave them untranslated. From my side, I'd like to have the po file that I manage always translated at 100%. Why? Because I'd like to see immediately the strings that I still need to translate, otherwise you will read over and over the untranslated strings. But it's up to you to decide.

My plugin is not translated, can I add manually the missing strings in the OpenPLi po files to have it translated too?

No never add manually missing strings/sentences into OpenPLi file to translate, for exemple plugin, because the po files are generated on a regular basis and every strings/sentences that is included in a po file but not found in the OpenPLi source code will just deleted. So you will lose your work.

Remark: I will explain later on how to properly translated plugins (stay tuned).

What are %s, %d, %f do I need to keep them?

%s, %d, %f, ... are respectively string, number, float number replacement strings, they are used in dynamically created string. So the same numbers of those special characters needs to be in your translation. You also need to keep them "attached" so %s cannot became % s in your translation. So be careful, especially if you trust suggested translation by PoEdit sometimes in the suggested translation those special important characters are changed.

What is \n?

\n is to force a carriage return so to preserve the layout of OpenPLi you need to respect them too. And there are some original strings that start with a \n this is normal, your translated string must also start with \n.

Do I need to respect spaces

Yes, some translation start or end with spaces, this is normal since they are part of a longer string so you need to preserve those starting and trailing spaces.

PoEdit

1. We recommend that you download and install PoEdit from this site (please consider to register it if you appreciate it): https://poedit.net/
2. Once installed go into: Preferences - Advanced - suppress the wrap line option and do not select preserve original file format

Can I edit po file without using PoEdit?

po files are just plain text, so yes of course any linux compatible text editor can do the job but PoEdit is real help to avoid some common mistake that you can make when editing it with a text editor.

PoEdit report warning in my po file, is it normal?

Yes, PoEdit can report warning that are not mistakes, for exemple a capital letter set when it is not in the original string, this is not blocking. If you are happy with you translation, don't care about warnings.
But if PoEdit report errors then you need to fix them, errors are important and will prevent you from saving the file. So you need to fix them all.

What are Fuzzy/To be reviewed lines in PoEdit?

The po files are generated based on the translatable strings that are in the source code, but the source code evolves and the strings are subject to change.
So when the script detect that an already translated string is changed in the source code, it is marked as fuzzy/to be reviewed, this mean that the string must be reviewed by the translators.
It can happen that the translation is still correct, so don't forgot to untick the fuzzy/to be reviewed flag in PoEdit because a fuzzy string is never displayed, only validated translation are.

During development process some well-known strings may evolve, so a translated string created for version X can turn into "fuzzy/to be reviewed" string in release X+1. So a translation file is really adapted for the version it is created for and it will need to reviewed with every OpenPLi version.

How to easily unwrap my file with PoEdit?

The po file that I proposed generates thousands of changed lines in github, is it normal?

Not really (except if you start a translation from scratch and work very hard). po files can have 2 format:

• the wrapped lines version where the editor wrap a big line into several smaller ones
• the unwrapped lines where the long line are remains untouched.

OpenPLi choose to include in there git the unwrapped version of the po file, so if you propose a wrapped po file this will generates thousands of changes.

But it is possible to easily unwrap your file with PoEdit:

1. Please open PoEdit, go into Preferences - Advanced - do not enable the wrap line after xx chars option and also do not select the preserve original file format.
2. Open up your po file and save it.

The new version will be an unwrapped version (size will be slightly smaller too).

Multi OS translation script pre-requisites

On Mac OSX

Install PoEdit from: https://poedit.net/

Since this package is downloaded from the Internet once you try to install it, it will be locked by the system, you need to go into System Preferences - Security & Confidentiality and in the General tab at the bottom click on the button: Open anyway.

• Once installed launch PoEdit and go into: Preferences - Advanced - suppress the wrap line option and do not select preserve original file format

Then open up a terminal and type:

git --version

If git is not installed you should be prompted to install it.

Then go to this website to install Homebrew: https://brew.sh/
Follow the instructions from the site. Once installed (perhaps a reboot is needed)

You open up a terminal and type:

brew update
brew upgrade
brew install gawk gettext gnu-sed python

Now you will be able to clone the OpenPLi repository:

cd
git clone https://github.com/OpenPLi/enigma2.git
cd ./enigma2/po
./updateallpo-multiOS.sh

On Windows

Install PoEdit from: https://poedit.net/

• Once installed launch PoEdit and go into: Preferences - Advanced - suppress the wrap line option and do not select preserve original file format

Go to Python.org and install Python: https://www.python.org/

Important: during installation of Python you need to select the checkbox Add Python to PATH otherwise Python is not accessible in git-bash, at the end of Python install I also click to allow path longer than 256 characters.

Go to GitForWindows and install it: https://gitforwindows.org/
Remark: seems that git-gui doesn't start on Windows, you need to launch it in Windows 8 compatibility mode. (but we won't use it anyway).

Then start the git-bash and type:

cd
git clone https://github.com/OpenPLi/enigma2.git
cd ./enigma2/po
./updateallpo-multiOS.sh

Debug: if the script doesn't work please test that Python is accessible into git-bash.
Start a git-bash command prompt and type: python -i then use exit() to leave Python.

If you didn't get into Python either:

• Python is not installed on your Windows
• Python is installed but the access path is not set into your Windows PATH variable (the easiest way to fix it is to reinstall Python and this time select Add Python into Path checkbox.)

On Ubuntu / Linux

sudo apt-get is Ubuntu command, it should also work on other distribution just adapt the package manager to it.

Install PoEdit from: https://poedit.net/

• Once installed launch PoEdit go into: Preferences - Advanced - suppress the wrap line option and do not select preserve original file format

Open up a terminal and type:

sudo apt-get update
sudo apt-get install python gettext gawk sed git

Now we will clone the OpenPLi repository:

cd
git clone https://github.com/OpenPLi/enigma2.git
cd ./enigma2/po
./updateallpo-multiOS.sh

updateallpo-multiOS.sh

updateallpo-multiOS.sh parameters

This script is created to be multi Operating System compatible. Please refer to section above to properly install the pre-requisites according to your Operating System.

Actions performed by this script are:

• Syncing with the remote server and remote branch (by default remote server: origin and default branch: develop)
• Create a local branch named: MyTranslation to work on
• Generate the latest .pot file and update all the .po files (+ create the .mo files too)

Once the script is finished you will get the very latest .po files so you can always ensure to work on an up-to-date translation file.

Once you have finish translating you can post your translation on the OpenPLi forum: https://forums.openpli.org/forum/55-en-enduser-support/

And we will push the translation for you in OpenPLi github.

The script has been tested on:

• Windows 10
• Mac OSX
• Ubuntu 16.04 & 18.04
• Raspbian (on Raspberry PI)

BE CAREFUL: if you change your po file from within this folder and run the script again, all your changes will be discarded!

Script must be launched from the location where you find it, so please don't specify the a full or relative path to launch. So first change directory (cd) into the folder then launch the script.

updateallpo-multiOS.sh possible options are:

 -r | --remote to specify the remote git to use,   default[origin]
 -b | --branch to specify the branch to translate, default[develop]
 -p | --python to specify the python runtime name, default[python]
 -n | --nodelete to keep the .pot files, useful to find where a message came from
 -h | --help   this text

-r | --remote

Default: origin
For more advanced user that have there own git fork, if you define OpenPLi as upstream you can select toward which remote server you want to update the branch.

Exemple:

./updateallpo-multiOS.sh -r upstream

-b|--branch

Default: develop
Sometimes OpenPLi create a new branch (typically rc) before releasing a new image. So it is sometimes asked to propose translation towards this branch if you want to have it in the announced futur image.

Exemple:

./updateallpo-multiOS.sh -b rc

-p|--python

Default: python
You can specify the name of the python runtime to launch, some system that have both Python 2.x and Python 3.x have python for 2.x and python3 for 3.x
So if you want to run the script towards a specific python version simply use:
./updateallpo-multiOS.sh -p python3

-n|--nodelete

Default: false
By default the generated .pot files are deleted, but it can be interesting if you want to know where a string came from to have a look into the enigma2-py.pot or enigma2-xml.pot file. So if you want to keep them use the option -n
./updateallpo-multiOS.sh -n

All options can be combined as needed.

Git command to push my changes

Please first read the following wiki page to create your github account and forked OpenPLi to your own git (origin), setup your own git as upstream and those are the pre-requisite for the following steps:

• https://wiki.openpli.org/Git-commands

Assuming that you have your git fork and git clone from the OpenPLi git (not yours!), and you have run the script, enter your local git clone:

cd enigma2/po
git branch
git remote -v

Will show you that you are now in the branch MyTranslation this branch was automatically created by the script.
Please check that origin is the OpenPLi repository and upstream is yours and not the opposite!
Let say that you have worked on the fr.po and are happy with the changes, you need to add it properly to your local git and push it to your online git.

git push --set-upstream upstream MyTranslation
git add fr.po
git commit -m "fr.po translation for develop branch"
git push

Then you can go to your online github and create the Pull Request (see git-command wiki).

Difference between updateallpo.sh and updateallpo-multiOS.sh

updateallpo.sh is acting exactly the same way as the normal build process does to update the po and generate the mo files, with the same constraint Python 2.x is the only supported version. It also doesn't update your local git clone, you need then to handle the git command yourself. So it is used by advanced users that are familiar with command line and git command.

updateallpo-multiOS.sh is doing more than updateallpo.sh, it update the git clone for you so you always have the very latest po files to work on for translation. Moreover, it is also compatible with Python 2.x and Python 3.x, it auto detects the python script to use and include more checks. It is design to be used by any user that want to help us with OpenPLi translation without the need to have a Linux style operating system.

Plugins translation

Plugins are spread across multiple git or subversion (svn) repositories.
Some plugins are grouped on the same repository, here are some urls:

• https://github.com/OpenPLi/enigma2-plugins
• https://github.com/E2OpenPlugins

Other plugins are on their creator repository.

Look into the repository file for the po file (often located into plugin_name/src/locale folder) and start working on it. If the po file doesn't exist yet, then there is probably a .pot file available. Based on the .pot file, you can easily start a new translation for your language.
Some plugins are closed-source, you need then to contact the author if you want to propose your translation services for this specific plugin.

How to add a new language file in https://github.com/OpenPLi/enigma2-plugins

Let's say that you want to add the fa.po file into the blindscan plugin.
Steps are (in bash shell or into git-bash):

cd
git clone https://github.com/OpenPLi/enigma2-plugins
cd enigma2-plugins
cd blindscan
cd po
touch fa.po
cd ../..
./updateallpo-multiOS.sh

BE CAREFULL: you always need to launch updateallpo-multiOS.sh from the folder you find it. So don't try to launch it with full or relative path, it won't work. In other words always launch it with: ./updateallpo-multiOS.sh. For Windows users the script must be launched into git-bash (it has the same pre-requisites as for the OpenPLi translation).

Explanation:

• We git clone the sources
• We go into the plugin po folder
• We create an empty translation file
• We update all the po file, so the newly created one will also be generated

So now you can start translating the plugins that you want.

You can upload your translation file to OpenPLi forum: https://forums.openpli.org/forum/55-en-enduser-support/ and it will be added for you into git.

Remark for advanced users: when you create a pull request to add a new language translation, please also include the Makefile.am since the new language is added to it too in the LANGS variable . This is done automatically by updateallpo-multiOS.sh