]>
Commit | Line | Data |
---|---|---|
1a47014f A |
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 | ### Extend Shaarli's translation | |
80 | ||
81 | If you're writing a custom theme, or a non official plugin, you might want to use the translation system, | |
82 | but you won't be able to able to override Shaarli's translation. | |
83 | ||
84 | However, you can add your own translation domain which extends the main translation list. | |
85 | ||
86 | > Note that you can find a live example of translation extension in the `demo_plugin`. | |
87 | ||
88 | First, create your translation files tree directory: | |
89 | ||
90 | ``` | |
91 | <your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/ | |
92 | ``` | |
93 | ||
94 | Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be | |
95 | `my_theme.po`. | |
96 | ||
97 | Users have to register your extension in their configuration with the parameter | |
98 | `translation.extensions.<domain>: <translation files path>`. | |
99 | ||
100 | Example: | |
101 | ||
102 | ```php | |
103 | if (! $conf->exists('translation.extensions.my_theme')) { | |
104 | $conf->set('translation.extensions.my_theme', '<your_module>/languages/'); | |
105 | $conf->write(true); | |
106 | } | |
107 | ``` | |
108 | ||
109 | > Note that the page needs to be reloaded after the registration. | |
110 | ||
111 | It is then recommended to create a custom translation function which will call the `t()` function with your domain. | |
112 | For example : | |
113 | ||
114 | ```php | |
115 | function my_theme_t($text, $nText = '', $nb = 1) | |
116 | { | |
117 | return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain. | |
118 | } | |
119 | ``` | |
120 | ||
121 | All strings which can be translated should be processed through your function: | |
122 | ||
123 | ```php | |
124 | my_theme_t('Comment'); | |
125 | my_theme_t('Comment', 'Comments', 2); | |
126 | ``` | |
127 | ||
128 | Or in templates: | |
129 | ||
130 | ```php | |
131 | {'Comment'|my_theme_t} | |
132 | {function="my_theme_t('Comment', 'Comments', 2)"} | |
133 | ``` | |
134 | ||
135 | > Note than in template, you need to visit your page at least once to generate a cache file. | |
136 | ||
137 | When you're done, open Poedit and load translation strings from sources: | |
138 | ||
139 | 1. `File > New` | |
140 | 2. Choose your language | |
141 | 3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`. | |
142 | 4. Go to `Catalog > Properties...` | |
143 | 5. Fill the `Translation Properties` tab | |
144 | 6. Add your source path in the `Sources Paths` tab | |
145 | 7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines: | |
146 | ||
147 | ``` | |
148 | my_theme_t | |
149 | my_theme_t:1,2 | |
150 | ``` | |
151 | ||
152 | Click on the "Update" button and you're free to start your translations! |