Translation documentation
This commit is contained in:
parent
6a65bc5798
commit
1a47014f99
8 changed files with 198 additions and 2 deletions
|
@ -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!
|
||||
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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/"
|
||||
}
|
||||
}
|
||||
} ?>
|
||||
```
|
||||
|
|
152
doc/md/Translations.md
Normal file
152
doc/md/Translations.md
Normal file
|
@ -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://<replace_domain>/
|
||||
http://<replace_domain>/?nonope
|
||||
http://<replace_domain>/?do=addlink
|
||||
http://<replace_domain>/?do=changepasswd
|
||||
http://<replace_domain>/?do=changetag
|
||||
http://<replace_domain>/?do=configure
|
||||
http://<replace_domain>/?do=tools
|
||||
http://<replace_domain>/?do=daily
|
||||
http://<replace_domain>/?post
|
||||
http://<replace_domain>/?do=export
|
||||
http://<replace_domain>/?do=import
|
||||
http://<replace_domain>/?do=login
|
||||
http://<replace_domain>/?do=picwall
|
||||
http://<replace_domain>/?do=pluginadmin
|
||||
http://<replace_domain>/?do=tagcloud
|
||||
http://<replace_domain>/?do=taglist
|
||||
```
|
||||
|
||||
#### Improve existing translation
|
||||
|
||||
In Poedit, click on "Edit a Translation", and from Shaarli's directory open
|
||||
`inc/languages/<lang>/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/<lang>/LC_MESSAGES/shaarli.po`.
|
||||
|
||||
Then select the language you want to create.
|
||||
|
||||
Click on `File > Save as...`, and save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po`.
|
||||
`<new language>` 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:
|
||||
|
||||
```
|
||||
<your_module>/languages/<ISO 3166-1 alpha-2 language code>/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.<domain>: <translation files path>`.
|
||||
|
||||
Example:
|
||||
|
||||
```php
|
||||
if (! $conf->exists('translation.extensions.my_theme')) {
|
||||
$conf->set('translation.extensions.my_theme', '<your_module>/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 `<your_module>/languages/<language code>/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!
|
|
@ -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
|
||||
|
|
BIN
doc/md/images/install-shaarli.png
Normal file
BIN
doc/md/images/install-shaarli.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 43 KiB |
BIN
doc/md/images/poedit-1.jpg
Normal file
BIN
doc/md/images/poedit-1.jpg
Normal file
Binary file not shown.
After Width: | Height: | Size: 71 KiB |
|
@ -43,6 +43,7 @@ pages:
|
|||
- Versioning and Branches: Versioning-and-Branches.md
|
||||
- Security: Security.md
|
||||
- Static analysis: Static-analysis.md
|
||||
- Translations: Translations.md
|
||||
- Theming: Theming.md
|
||||
- Unit tests: Unit-tests.md
|
||||
- Unit tests inside Docker: Unit-tests-Docker.md
|
||||
|
|
Loading…
Reference in a new issue