aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--doc/md/Download-and-Installation.md4
-rw-r--r--doc/md/Server-requirements.md1
-rw-r--r--doc/md/Shaarli-configuration.md21
-rw-r--r--doc/md/Translations.md152
-rw-r--r--doc/md/Upgrade-and-migration.md21
-rw-r--r--doc/md/images/install-shaarli.pngbin0 -> 44376 bytes
-rw-r--r--doc/md/images/poedit-1.jpgbin0 -> 72956 bytes
-rw-r--r--mkdocs.yml1
8 files changed, 198 insertions, 2 deletions
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index e5e929ef..59a1b7da 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -36,6 +36,7 @@ In most cases, download Shaarli from the [releases](https://github.com/shaarli/S
36$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ 36$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
37$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git . 37$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
38$ composer install --no-dev --prefer-dist 38$ composer install --no-dev --prefer-dist
39$ make translate
39``` 40```
40 41
41## Stable version 42## Stable version
@@ -83,13 +84,14 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
83# install/update third-party dependencies 84# install/update third-party dependencies
84$ cd /path/to/shaarli 85$ cd /path/to/shaarli
85$ composer install --no-dev --prefer-dist 86$ composer install --no-dev --prefer-dist
87$ make translate
86``` 88```
87 89
88## Finish Installation 90## Finish Installation
89 91
90Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser. 92Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
91 93
92![install screenshot](http://i.imgur.com/wuMpDSN.png) 94![install screenshot](images/install-shaarli.png)
93 95
94Setup your Shaarli installation, and it's ready to use! 96Setup your Shaarli installation, and it's ready to use!
95 97
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
index 707af762..400b85a9 100644
--- a/doc/md/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -39,3 +39,4 @@ Extension | Required? | Usage
39[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing 39[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
40[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) 40[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
41[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way 41[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
42[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 99b25ba7..920c7e27 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -81,6 +81,20 @@ _These settings should not be edited_
81- **page_cache**: Shaarli's internal cache directory. 81- **page_cache**: Shaarli's internal cache directory.
82- **ban_file**: Banned IP file path. 82- **ban_file**: Banned IP file path.
83 83
84### Translation
85
86- **language**: translation language (also see [Translations](Translations))
87 - **auto** (default): The translation language is chosen from the browser locale.
88 It means that the language can be different for 2 different visitors depending on their locale.
89 - **en**: Use the English translation.
90 - **fr**: Use the French translation.
91- **mode**:
92 - **auto** or **php** (default): Use the PHP implementation of gettext (slower)
93 - **gettext**: Use PHP builtin gettext extension
94 (faster, but requires `php-gettext` to be installed and to reload the web server on update)
95- **extension**: Translation extensions for custom themes or plugins.
96Must be an associative array: `translation domain => translation path`.
97
84### Updates 98### Updates
85 99
86- **check_updates**: Enable or disable update check to the git repository. 100- **check_updates**: Enable or disable update check to the git repository.
@@ -211,6 +225,13 @@ _These settings should not be edited_
211 "plugins": { 225 "plugins": {
212 "WALLABAG_URL": "http://demo.wallabag.org", 226 "WALLABAG_URL": "http://demo.wallabag.org",
213 "WALLABAG_VERSION": "1" 227 "WALLABAG_VERSION": "1"
228 },
229 "translation": {
230 "language": "fr",
231 "mode": "php",
232 "extensions": {
233 "demo": "plugins/demo_plugin/languages/"
234 }
214 } 235 }
215} ?> 236} ?>
216``` 237```
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!
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 7033cd41..1dc07339 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -39,7 +39,10 @@ We recommend that you use the latest release tarball with the `-full` suffix. It
39 39
40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! 40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
41 41
42After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more details). 42If you use translations in gettext mode - meaning you manually changed the default mode -,
43reload your web server.
44
45After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
43 46
44## Upgrading with Git 47## Upgrading with Git
45 48
@@ -72,6 +75,14 @@ Updating dependencies
72 Downloading: 100% 75 Downloading: 100%
73``` 76```
74 77
78Shaarli >= `v0.9.2` supports translations:
79
80```bash
81$ make translate
82```
83
84If you use translations in gettext mode, reload your web server.
85
75### Migrating and upgrading from Sebsauvage's repository 86### Migrating and upgrading from Sebsauvage's repository
76 87
77If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy. 88If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
@@ -151,6 +162,14 @@ Updating dependencies
151 Downloading: 100% 162 Downloading: 100%
152``` 163```
153 164
165Shaarli >= `v0.9.2` supports translations:
166
167```bash
168$ make translate
169```
170
171If you use translations in gettext mode, reload your web server.
172
154Optionally, you can delete information related to the legacy version: 173Optionally, you can delete information related to the legacy version:
155 174
156```bash 175```bash
diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png
new file mode 100644
index 00000000..7ae33816
--- /dev/null
+++ b/doc/md/images/install-shaarli.png
Binary files differ
diff --git a/doc/md/images/poedit-1.jpg b/doc/md/images/poedit-1.jpg
new file mode 100644
index 00000000..673ae6d6
--- /dev/null
+++ b/doc/md/images/poedit-1.jpg
Binary files differ
diff --git a/mkdocs.yml b/mkdocs.yml
index 03a7a34e..8617ea45 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,6 +43,7 @@ pages:
43 - Versioning and Branches: Versioning-and-Branches.md 43 - Versioning and Branches: Versioning-and-Branches.md
44 - Security: Security.md 44 - Security: Security.md
45 - Static analysis: Static-analysis.md 45 - Static analysis: Static-analysis.md
46 - Translations: Translations.md
46 - Theming: Theming.md 47 - Theming: Theming.md
47 - Unit tests: Unit-tests.md 48 - Unit tests: Unit-tests.md
48 - Unit tests inside Docker: Unit-tests-Docker.md 49 - Unit tests inside Docker: Unit-tests-Docker.md