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/
|
$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
|
||||||
$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
|
$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
|
||||||
$ composer install --no-dev --prefer-dist
|
$ composer install --no-dev --prefer-dist
|
||||||
|
$ make translate
|
||||||
```
|
```
|
||||||
|
|
||||||
## Stable version
|
## Stable version
|
||||||
|
@ -83,13 +84,14 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
|
||||||
# install/update third-party dependencies
|
# install/update third-party dependencies
|
||||||
$ cd /path/to/shaarli
|
$ cd /path/to/shaarli
|
||||||
$ composer install --no-dev --prefer-dist
|
$ composer install --no-dev --prefer-dist
|
||||||
|
$ make translate
|
||||||
```
|
```
|
||||||
|
|
||||||
## Finish Installation
|
## Finish Installation
|
||||||
|
|
||||||
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
|
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!
|
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-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-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-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.
|
- **page_cache**: Shaarli's internal cache directory.
|
||||||
- **ban_file**: Banned IP file path.
|
- **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
|
### Updates
|
||||||
|
|
||||||
- **check_updates**: Enable or disable update check to the git repository.
|
- **check_updates**: Enable or disable update check to the git repository.
|
||||||
|
@ -211,6 +225,13 @@ _These settings should not be edited_
|
||||||
"plugins": {
|
"plugins": {
|
||||||
"WALLABAG_URL": "http://demo.wallabag.org",
|
"WALLABAG_URL": "http://demo.wallabag.org",
|
||||||
"WALLABAG_VERSION": "1"
|
"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!
|
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
|
## Upgrading with Git
|
||||||
|
|
||||||
|
@ -72,6 +75,14 @@ Updating dependencies
|
||||||
Downloading: 100%
|
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
|
### 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.
|
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%
|
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:
|
Optionally, you can delete information related to the legacy version:
|
||||||
|
|
||||||
```bash
|
```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
|
- Versioning and Branches: Versioning-and-Branches.md
|
||||||
- Security: Security.md
|
- Security: Security.md
|
||||||
- Static analysis: Static-analysis.md
|
- Static analysis: Static-analysis.md
|
||||||
|
- Translations: Translations.md
|
||||||
- Theming: Theming.md
|
- Theming: Theming.md
|
||||||
- Unit tests: Unit-tests.md
|
- Unit tests: Unit-tests.md
|
||||||
- Unit tests inside Docker: Unit-tests-Docker.md
|
- Unit tests inside Docker: Unit-tests-Docker.md
|
||||||
|
|
Loading…
Reference in a new issue