doc/md/dev/Translations.md

   1 ## Translations
   2
   3 Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
   4 since `>= v0.9.2`.
   5
   6 Note that only the `default` theme supports translations.
   7
   8 ### Contributing
   9
  10 We encourage the community to contribute to Shaarli translations, either by improving existing translations or submitting a new language.
  11
  12 Contributing to the translation does not require software development knowledge.
  13
  14 Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`) is not stored on the repository, and is generated during the release process.
  15
  16
  17 ### How to
  18
  19 Install [Poedit](https://poedit.net/) (used to extract strings to translate from the PHP source code, and generate `.po` files).
  20
  21 Due to the usage of a template engine, it's important to generate PHP cache files to extract every translatable string. You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended) or visit every template page in your browser to generate cache files, while logged in. Here is a list :
  22
  23 ```
  24 http://<replace_domain>/
  25 http://<replace_domain>/login
  26 http://<replace_domain>/daily
  27 http://<replace_domain>/tags/cloud
  28 http://<replace_domain>/tags/list
  29 http://<replace_domain>/picture-wall
  30 http://<replace_domain>/?nonope
  31 http://<replace_domain>/admin/add-shaare
  32 http://<replace_domain>/admin/password
  33 http://<replace_domain>/admin/tags
  34 http://<replace_domain>/admin/configure
  35 http://<replace_domain>/admin/tools
  36 http://<replace_domain>/admin/shaare
  37 http://<replace_domain>/admin/export
  38 http://<replace_domain>/admin/import
  39 http://<replace_domain>/admin/plugins
  40 ```
  41
  42
  43 #### Improve existing translations
  44
  45 - In Poedit, click on "Edit a Translation
  46 - Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
  47 - The existing list of translatable strings should load
  48 - Click on the "Update" button.
  49 - Start editing translations.
  50
  51 ![poedit-screenshot](images/poedit-1.jpg)
  52
  53 Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
  54
  55
  56 #### Add a new language
  57
  58 - In Poedit select "Create New Translation"
  59 - Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
  60 - Select the language you want to create.
  61 - Click on `File > Save as...`, save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po` (`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format in lowercase - e.g. `de` for German)
  62 - Click on the "Update" button
  63 - Start editing translations.
  64
  65 Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
  66
  67
  68 ### Theme translations
  69
  70 [Theme](Theming) translation extensions are loaded automatically if they're present.
  71
  72 As a theme developer, all you have to do is to add the `.po` and `.mo` compiled file like this:
  73
  74 ```
  75 tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.po
  76 tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.mo
  77 ```
  78
  79 Where `<lang>` is the ISO 3166-1 alpha-2 language code.
  80
  81 Read the following section "Extend Shaarli's translation" to learn how to generate those files.
  82
  83
  84 ### Extend Shaarli's translation
  85
  86 If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
  87 but you won't be able to able to override Shaarli's translation.
  88
  89 However, you can add your own translation domain which extends the main translation list.
  90
  91 > Note that you can find a live example of translation extension in the `demo_plugin`.
  92
  93 First, create your translation files tree directory:
  94
  95 ```
  96 <your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
  97 ```
  98
  99 Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
 100 `my_theme.po`.
 101
 102 Users have to register your extension in their configuration with the parameter
 103 `translation.extensions.<domain>: <translation files path>`.
 104
 105 Example:
 106
 107 ```php
 108 if (! $conf->exists('translation.extensions.my_theme')) {
 109     $conf->set('translation.extensions.my_theme', '<your_module>/languages/');
 110     $conf->write(true);
 111 }
 112 ```
 113
 114 > Note that the page needs to be reloaded after the registration.
 115
 116 It is then recommended to create a custom translation function which will call the `t()` function with your domain.
 117 For example :
 118
 119 ```php
 120 function my_theme_t($text, $nText = '', $nb = 1)
 121 {
 122     return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
 123 }
 124 ```
 125
 126 All strings which can be translated should be processed through your function:
 127
 128 ```php
 129 my_theme_t('Comment');
 130 my_theme_t('Comment', 'Comments', 2);
 131 ```
 132
 133 Or in templates:
 134
 135 ```php
 136 {'Comment'|my_theme_t}
 137 {function="my_theme_t('Comment', 'Comments', 2)"}
 138 ```
 139
 140 > Note than in template, you need to visit your page at least once to generate a cache file.
 141
 142 When you're done, open Poedit and load translation strings from sources:
 143
 144   1. `File > New`
 145   2. Choose your language
 146   3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
 147   4. Go to `Catalog > Properties...`
 148   5. Fill the `Translation Properties` tab
 149   6. Add your source path in the `Sources Paths` tab
 150   7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
 151
 152 ```
 153 my_theme_t
 154 my_theme_t:1,2
 155 ```
 156
 157 Click on the "Update" button and you're free to start your translations!