X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=doc%2Ftranslations.md;h=8b7077b6b17617e97779eb2a46b28bd7d5566b83;hb=84dfda1ccd50e8b5a563f6638fde8c488bcd75bf;hp=b874e9ea2e8a84b717fe590cb9fe29ec081840dd;hpb=244de7d750a9bde8fd1941ab41cd6731d16fd899;p=friendica.git diff --git a/doc/translations.md b/doc/translations.md index b874e9ea2e..8b7077b6b1 100644 --- a/doc/translations.md +++ b/doc/translations.md @@ -1,95 +1,96 @@ Friendica translations ====================== -Translation Process -------------------- - -The strings used in the UI of Friendica is translated at [Transifex] [1] and then -included in the git repository at github. If you want to help with translation -for any language, be it correcting terms or translating friendica to a -currently not supported language, please register an account at transifex.com -and contact the friendica translation team there. - -Translating friendica is simple. Just use the online tool at transifex. If you -don't want to deal with git & co. that is fine, we check the status of the -translations regularly and import them into the source tree at github so that -others can use them. - -We do not include every translation from transifex in the source tree to avoid -a scattered and disturbed overall experience. As an uneducated guess we have a -lower limit of 50% translated strings before we include the language (for the -core message.po file, addont translation will be included once all strings of -an addon are translated. This limit is judging only by the amount of translated -strings under the assumption that the most prominent strings for the UI will be -translated first by a translation team. If you feel your translation useable -before this limit, please contact us and we will probably include your teams -work in the source tree. - -If you want to get your work into the source tree yourself, feel free to do so -and contact us with and question that arises. The process is simple and -friendica ships with all the tools necessary. - -The location of the translated files in the source tree is - /view/LNG-CODE/ -where LNG-CODE is the language code used, e.g. de for German or fr for French. -For the email templates (the *.tpl files) just place them into the directory -and you are done. The translated strings come as a "message.po" file from -transifex which needs to be translated into the PHP file friendica uses. To do -so, place the file in the directory mentioned above and use the "po2php" -utility from the util directory of your friendica installation. - -Assuming you want to convert the German localization which is placed in -view/de/message.po you would do the following. - - 1. Navigate at the command prompt to the base directory of your - friendica installation - - 2. Execute the po2php script, which will place the translation - in the strings.php file that is used by friendica. - - $> php util/po2php.php view/de/message.po - - The output of the script will be placed at view/de/strings.php where - froemdoca os expecting it, so you can test your translation mmediately. - - 3. Visit your friendica page to check if it still works in the language you - just translated. If not try to find the error, most likely PHP will give - you a hint in the log/warnings.about the error. - - For debugging you can also try to "run" the file with PHP. This should - not give any output if the file is ok but might give a hint for - searching the bug in the file. - - $> php view/de/strings.php - - 4. commit the two files with a meaningful commit message to your git - repository, push it to your fork of the friendica repository at github and - issue a pull request for that commit. - -Utilities ---------- - -Additional to the po2php script there are some more utilities for translation -in the "util" directory of the friendica source tree. If you only want to -translate friendica into another language you wont need any of these tools most -likely but it gives you an idea how the translation process of friendica -works. - -For further information see the utils/README file. - -Known Problems --------------- - -Friendica uses the language setting of the visitors browser to determain the -language for the UI. Most of the time this works, but there are some known -quirks. - -One is that some browsers, like Safari, do the setting to "de-de" but friendica -only has a "de" localisation. A workaround would be to add a symbolic link -from - $friendica/view/de-de -pointing to - $friendica/view/de - -[1]: https://www.transifex.com/projects/p/friendica/ +* [Home](help) +## Overview + +The Friendica translation process is based on `gettext` PO files. + +Basic worflow: +1. `xgettext` is used to collect translation strings across the project in the authoritative PO file located in `view/lang/C/messages.po`. +2. This file makes translations strings available at [the Transifex Friendica page](https://www.transifex.com/Friendica/friendica/dashboard/). +3. The translation itself is done at Transifex by volunteers. +4. The resulting PO files by languages are manually updated in `view/lang//messages.po`. +5. PO files are converted to PHP arrays in `view/lang//strings.php` that are ultimately used by Friendica to display the translations. + +## Translate Friendica in your favorite language + +Thank you for your interest in improving Friendica's translation! +Please register a free Transifex account and ask over at [the Transifex Friendica page](https://www.transifex.com/Friendica/friendica/dashboard/) to join the translation team for your favorite language. + +As a rule of thumb, we add support for a language in Friendica when at least 50% of the strings have been translated to avoid a scattered experience. +For addons, we add support for a language when if we already support the language in Friendica. + +## Add new translation strings + +### Supported gettext version + +We currently support the gettext version 0.19.8.1 and actively check new translation strings with this version. + +If you don't use this version, it's possible that our checks fail (f.e. because of tiny differences at linebreaks). +In case you do have a Docker environment, you can easily update the translations with the following command: +```shell +docker run --rm -v $PWD:/data -w /data friendicaci/transifex bin/run_xgettext.sh +``` + +### Core + +Once you have added new translation strings in your code changes, please run `bin/run_xgettext.sh` from the base Friendica directory and commit the updated `view/lang/C/messages.po` to your branch. + +### Addon + +If you have the `friendica-addons` repository in the `addon` directory of your Friendica cloned repository, just run `bin/run_xgettext.sh -a ` from the base Friendica directory. + +Otherwise: + + cd /path/to/friendica-addons/ + /path/to/friendica/bin/run_xgettext.sh -s + +In either case, you need to commit the updated `/lang/C/messages.po` to your working branch. + +## Update translations from Transifex + +Please download the Transifex file "for use" in `view/lang//messages.po`. + +Then run `bin/console po2php view/lang//messages.po` to update the related `strings.php` file and commit both files to your working branch. + +### Using the Transifex client + +Transifex has a client program which allows you to sync files between your cloned Friendica repository and Transifex. +Help for the client can be found at the [Transifex Help Center](https://docs.transifex.com/client/introduction). +Here we will only cover basic usage. + +After installation of the client, you should have a `tx` command available on your system. +To use it, first create a configuration file with your credentials. +On Linux this file should be placed into your home directory `~/.transifexrc`. +The content of the file should be something like the following: + + [https://www.transifex.com] + username = user + token = + password = p@ssw0rd + hostname = https://www.transifex.com + +Since Friendica version 3.5.1 we ship configuration files for the Transifex client in the core repository and the addon repository in `.tx/config`. +To update the PO files after you have translated strings of e.g. Esperanto on the Transifex website you can use `tx` to download the updated PO file in the right location. + + $> tx pull -l eo + +Then run `bin/console po2php view/lang//messages.po` to update the related `strings.php` file and commit both files to your working branch. + +## Translation functions usage + +### Basic usage + +- `Friendica\DI::l10n()->t('Label')` => `Label` +- `Friendica\DI::l10n()->t('Label %s', 'test')` => `Label test` + +### Plural + +- `Friendica\DI::l10n()->tt('Label', 'Labels', 1)` => `Label` +- `Friendica\DI::l10n()->tt('Label', 'Labels', 3)` => `Labels` +- `Friendica\DI::l10n()->tt('%d Label', '%d Labels', 1)` => `1 Label` +- `Friendica\DI::l10n()->tt('%d Label', '%d Labels', 3)` => `3 Labels` +- `Friendica\DI::l10n()->tt('%d Label', 'Labels %2%s %3%s', 1, 'test', 'test2')` => `Label test test2` +- `Friendica\DI::l10n()->tt('%d Label', 'Labels %2%s %3%s', 3, 'test', 'test2')` => `Labels test test2`