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