aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Translations.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/Translations.md')
-rw-r--r--doc/md/Translations.md152
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/md/Translations.md b/doc/md/Translations.md
new file mode 100644
index 00000000..54a36655
--- /dev/null
+++ b/doc/md/Translations.md
@@ -0,0 +1,152 @@
1## Translations
2
3Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
4since `>= v0.9.2`.
5
6Note that only the `default` theme supports translations.
7
8### Contributing
9
10We encourage the community to contribute to Shaarli's translation either by improving existing
11translations or submitting a new language.
12
13Contributing to the translation does not require development skill.
14
15Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`)
16is not stored on the repository, and is generated during the release process.
17
18### How to
19
20First, install [Poedit](https://poedit.net/) tool.
21
22Poedit 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
25every translatable string.
26
27You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended)
28or visit every template page in your browser to generate cache files, while logged in.
29
30Here is a list :
31
32```
33http://<replace_domain>/
34http://<replace_domain>/?nonope
35http://<replace_domain>/?do=addlink
36http://<replace_domain>/?do=changepasswd
37http://<replace_domain>/?do=changetag
38http://<replace_domain>/?do=configure
39http://<replace_domain>/?do=tools
40http://<replace_domain>/?do=daily
41http://<replace_domain>/?post
42http://<replace_domain>/?do=export
43http://<replace_domain>/?do=import
44http://<replace_domain>/?do=login
45http://<replace_domain>/?do=picwall
46http://<replace_domain>/?do=pluginadmin
47http://<replace_domain>/?do=tagcloud
48http://<replace_domain>/?do=taglist
49```
50
51#### Improve existing translation
52
53In Poedit, click on "Edit a Translation", and from Shaarli's directory open
54`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
55
56The existing list of translatable strings should have been loaded, then click on the "Update" button.
57
58You can start editing the translation.
59
60![poedit-screenshot](images/poedit-1.jpg)
61
62Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
63
64#### Add a new language
65
66Open Poedit and select "Create New Translation", then from Shaarli's directory open
67`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
68
69Then select the language you want to create.
70
71Click 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)
73format in lowercase (e.g. `de` for German).
74
75Then click on the "Update" button, and you can start to translate every available string.
76
77Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
78
79### Extend Shaarli's translation
80
81If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
82but you won't be able to able to override Shaarli's translation.
83
84However, 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
88First, create your translation files tree directory:
89
90```
91<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
92```
93
94Your `.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
97Users have to register your extension in their configuration with the parameter
98`translation.extensions.<domain>: <translation files path>`.
99
100Example:
101
102```php
103if (! $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
111It is then recommended to create a custom translation function which will call the `t()` function with your domain.
112For example :
113
114```php
115function 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
121All strings which can be translated should be processed through your function:
122
123```php
124my_theme_t('Comment');
125my_theme_t('Comment', 'Comments', 2);
126```
127
128Or 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
137When 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```
148my_theme_t
149my_theme_t:1,2
150```
151
152Click on the "Update" button and you're free to start your translations!