diff options
Diffstat (limited to 'doc/md/Translations.md')
-rw-r--r-- | doc/md/Translations.md | 164 |
1 files changed, 0 insertions, 164 deletions
diff --git a/doc/md/Translations.md b/doc/md/Translations.md deleted file mode 100644 index c23ec962..00000000 --- a/doc/md/Translations.md +++ /dev/null | |||
@@ -1,164 +0,0 @@ | |||
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>/admin/add-shaare | ||
36 | http://<replace_domain>/admin/password | ||
37 | http://<replace_domain>/admin/tags | ||
38 | http://<replace_domain>/admin/configure | ||
39 | http://<replace_domain>/admin/tools | ||
40 | http://<replace_domain>/daily | ||
41 | http://<replace_domain>/admin/shaare | ||
42 | http://<replace_domain>/admin/export | ||
43 | http://<replace_domain>/admin/import | ||
44 | http://<replace_domain>/login | ||
45 | http://<replace_domain>/picture-wall | ||
46 | http://<replace_domain>/admin/plugins | ||
47 | http://<replace_domain>/tags/cloud | ||
48 | http://<replace_domain>/tags/list | ||
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! | ||