doc/translations.md

   1 Friendica translations
   2 ======================
   3
   4 * [Home](help)
   5
   6 ## Overview
   7
   8 The Friendica translation process is based on `gettext` PO files.
   9
  10 Basic worflow:
  11 1. `xgettext` is used to collect translation strings across the project in the authoritative PO file located in `view/lang/C/messages.po`.
  12 2. This file makes translations strings available at [the Transifex Friendica page](https://www.transifex.com/Friendica/friendica/dashboard/).
  13 3. The translation itself is done at Transifex by volunteers.
  14 4. The resulting PO files by languages are manually updated in `view/lang/<language>/messages.po`.
  15 5. PO files are converted to PHP arrays in `view/lang/<language>/strings.php` that are ultimately used by Friendica to display the translations.
  16
  17 ## Translate Friendica in your favorite language
  18
  19 Thank you for your interest in improving Friendica's translation!
  20 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.
  21
  22 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.
  23 For addons, we add support for a language when if we already support the language in Friendica.
  24
  25 ## Add new translation strings
  26
  27 ### Core
  28
  29 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.
  30
  31 ### Addon
  32
  33 If you have the `friendica-addons` repository in the `addon` directory of your Friendica cloned repository, just run `bin/run_xgettext.sh -a <addon_name>` from the base Friendica directory.
  34
  35 Otherwise:
  36
  37         cd /path/to/friendica-addons/<addon_name>
  38         /path/to/friendica/bin/run_xgettext.sh -s
  39
  40 In either case, you need to commit the updated `<addon_name>/lang/C/messages.po` to your working branch.
  41
  42 ## Update translations from Transifex
  43
  44 Please download the Transifex file "for use" in `view/lang/<language>/messages.po`.
  45
  46 Then run `bin/console po2php view/lang/<language>/messages.po` to update the related `strings.php` file and commit both files to your working branch.
  47
  48 ### Using the Transifex client
  49
  50 Transifex has a client program which allows you to sync files between your cloned Friendica repository and Transifex.
  51 Help for the client can be found at the [Transifex Help Center](https://docs.transifex.com/client/introduction).
  52 Here we will only cover basic usage.
  53
  54 After installation of the client, you should have a `tx` command available on your system.
  55 To use it, first create a configuration file with your credentials.
  56 On Linux this file should be placed into your home directory `~/.transifexrc`.
  57 The content of the file should be something like the following:
  58
  59     [https://www.transifex.com]
  60     username = user
  61     token =
  62     password = p@ssw0rd
  63     hostname = https://www.transifex.com
  64
  65 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`.
  66 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.
  67
  68     $> tx pull -l eo
  69
  70 Then run `bin/console po2php view/lang/<language>/messages.po` to update the related `strings.php` file and commit both files to your working branch.
  71
  72 ## Translation functions usage
  73
  74 ### Basic usage
  75
  76 - `Friendica\DI::l10n()->t('Label')` => `Label`
  77 - `Friendica\DI::l10n()->t('Label %s', 'test')` => `Label test`
  78
  79 ### Plural
  80
  81 - `Friendica\DI::l10n()->tt('Label', 'Labels', 1)` => `Label`
  82 - `Friendica\DI::l10n()->tt('Label', 'Labels', 3)` => `Labels`
  83 - `Friendica\DI::l10n()->tt('%d Label', '%d Labels', 1)` => `1 Label`
  84 - `Friendica\DI::l10n()->tt('%d Label', '%d Labels', 3)` => `3 Labels`
  85 - `Friendica\DI::l10n()->tt('%d Label', 'Labels %2%s %3%s', 1, 'test', 'test2')` => `Label test test2`
  86 - `Friendica\DI::l10n()->tt('%d Label', 'Labels %2%s %3%s', 3, 'test', 'test2')` => `Labels test test2`