From 1a47014f99d2f7aae00d37e62e0364d4eaa1ce29 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 1 Sep 2017 18:47:32 +0200 Subject: Translation documentation --- doc/md/Download-and-Installation.md | 4 +- doc/md/Server-requirements.md | 1 + doc/md/Shaarli-configuration.md | 21 +++++ doc/md/Translations.md | 152 ++++++++++++++++++++++++++++++++++++ doc/md/Upgrade-and-migration.md | 21 ++++- doc/md/images/install-shaarli.png | Bin 0 -> 44376 bytes doc/md/images/poedit-1.jpg | Bin 0 -> 72956 bytes 7 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 doc/md/Translations.md create mode 100644 doc/md/images/install-shaarli.png create mode 100644 doc/md/images/poedit-1.jpg (limited to 'doc') 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 $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ $ git clone -b v0.9 https://github.com/shaarli/Shaarli.git . $ composer install --no-dev --prefer-dist +$ make translate ``` ## Stable version @@ -83,13 +84,14 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ # install/update third-party dependencies $ cd /path/to/shaarli $ composer install --no-dev --prefer-dist +$ make translate ``` ## Finish Installation Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser. -![install screenshot](http://i.imgur.com/wuMpDSN.png) +![install screenshot](images/install-shaarli.png) Setup your Shaarli installation, and it's ready to use! 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 [`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->รจ->f`) [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way +[`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_ - **page_cache**: Shaarli's internal cache directory. - **ban_file**: Banned IP file path. +### Translation + +- **language**: translation language (also see [Translations](Translations)) + - **auto** (default): The translation language is chosen from the browser locale. + It means that the language can be different for 2 different visitors depending on their locale. + - **en**: Use the English translation. + - **fr**: Use the French translation. +- **mode**: + - **auto** or **php** (default): Use the PHP implementation of gettext (slower) + - **gettext**: Use PHP builtin gettext extension + (faster, but requires `php-gettext` to be installed and to reload the web server on update) +- **extension**: Translation extensions for custom themes or plugins. +Must be an associative array: `translation domain => translation path`. + ### Updates - **check_updates**: Enable or disable update check to the git repository. @@ -211,6 +225,13 @@ _These settings should not be edited_ "plugins": { "WALLABAG_URL": "http://demo.wallabag.org", "WALLABAG_VERSION": "1" + }, + "translation": { + "language": "fr", + "mode": "php", + "extensions": { + "demo": "plugins/demo_plugin/languages/" + } } } ?> ``` 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 @@ +## Translations + +Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations +since `>= v0.9.2`. + +Note that only the `default` theme supports translations. + +### Contributing + +We encourage the community to contribute to Shaarli's translation either by improving existing +translations or submitting a new language. + +Contributing to the translation does not require development skill. + +Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`) +is not stored on the repository, and is generated during the release process. + +### How to + +First, install [Poedit](https://poedit.net/) tool. + +Poedit will extract strings to translate from the PHP source code. + +**Important**: due to the usage of a template engine, it's important to generate PHP cache files to extract +every translatable string. + +You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended) +or visit every template page in your browser to generate cache files, while logged in. + +Here is a list : + +``` +http:/// +http:///?nonope +http:///?do=addlink +http:///?do=changepasswd +http:///?do=changetag +http:///?do=configure +http:///?do=tools +http:///?do=daily +http:///?post +http:///?do=export +http:///?do=import +http:///?do=login +http:///?do=picwall +http:///?do=pluginadmin +http:///?do=tagcloud +http:///?do=taglist +``` + +#### Improve existing translation + +In Poedit, click on "Edit a Translation", and from Shaarli's directory open +`inc/languages//LC_MESSAGES/shaarli.po`. + +The existing list of translatable strings should have been loaded, then click on the "Update" button. + +You can start editing the translation. + +![poedit-screenshot](images/poedit-1.jpg) + +Save when you're done, then you can submit a pull request containing the updated `shaarli.po`. + +#### Add a new language + +Open Poedit and select "Create New Translation", then from Shaarli's directory open +`inc/languages//LC_MESSAGES/shaarli.po`. + +Then select the language you want to create. + +Click on `File > Save as...`, and save your file in `/inc/language//LC_MESSAGES/shaarli.po`. +`` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) +format in lowercase (e.g. `de` for German). + +Then click on the "Update" button, and you can start to translate every available string. + +Save when you're done, then you can submit a pull request containing the new `shaarli.po`. + +### Extend Shaarli's translation + +If you're writing a custom theme, or a non official plugin, you might want to use the translation system, +but you won't be able to able to override Shaarli's translation. + +However, you can add your own translation domain which extends the main translation list. + +> Note that you can find a live example of translation extension in the `demo_plugin`. + +First, create your translation files tree directory: + +``` +/languages//LC_MESSAGES/ +``` + +Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be +`my_theme.po`. + +Users have to register your extension in their configuration with the parameter +`translation.extensions.: `. + +Example: + +```php +if (! $conf->exists('translation.extensions.my_theme')) { + $conf->set('translation.extensions.my_theme', '/languages/'); + $conf->write(true); +} +``` + +> Note that the page needs to be reloaded after the registration. + +It is then recommended to create a custom translation function which will call the `t()` function with your domain. +For example : + +```php +function my_theme_t($text, $nText = '', $nb = 1) +{ + return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain. +} +``` + +All strings which can be translated should be processed through your function: + +```php +my_theme_t('Comment'); +my_theme_t('Comment', 'Comments', 2); +``` + +Or in templates: + +```php +{'Comment'|my_theme_t} +{function="my_theme_t('Comment', 'Comments', 2)"} +``` + +> Note than in template, you need to visit your page at least once to generate a cache file. + +When you're done, open Poedit and load translation strings from sources: + + 1. `File > New` + 2. Choose your language + 3. Save your `PO` file in `/languages//LC_MESSAGES/my_theme.po`. + 4. Go to `Catalog > Properties...` + 5. Fill the `Translation Properties` tab + 6. Add your source path in the `Sources Paths` tab + 7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines: + +``` +my_theme_t +my_theme_t:1,2 +``` + +Click 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 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! -After 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). +If you use translations in gettext mode - meaning you manually changed the default mode -, +reload your web server. + +After 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). ## Upgrading with Git @@ -72,6 +75,14 @@ Updating dependencies Downloading: 100% ``` +Shaarli >= `v0.9.2` supports translations: + +```bash +$ make translate +``` + +If you use translations in gettext mode, reload your web server. + ### Migrating and upgrading from Sebsauvage's repository If 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 Downloading: 100% ``` +Shaarli >= `v0.9.2` supports translations: + +```bash +$ make translate +``` + +If you use translations in gettext mode, reload your web server. + Optionally, you can delete information related to the legacy version: ```bash diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png new file mode 100644 index 00000000..7ae33816 Binary files /dev/null and b/doc/md/images/install-shaarli.png differ diff --git a/doc/md/images/poedit-1.jpg b/doc/md/images/poedit-1.jpg new file mode 100644 index 00000000..673ae6d6 Binary files /dev/null and b/doc/md/images/poedit-1.jpg differ -- cgit v1.2.3