Labels
======
This extension allows you to use translatable labels for your site. While it
does not allow for fully multilingual sites, you can easily translate labels
and short snippets of text to different languages.
After installation, there will be a new menu-item to access the page where you
can modify and mange the translations:
If you go to that page, you'll be able to manage the translations in a
spreadsheet-like grid:
Configuration
-------------
The configuration file is pretty self-explanatory. If you're upgrading from a
previous version of this extension, please read the `config.yml.dist` file, to
see what's been changed.
**Options:**
- `languages`: The array of supported languages. It's advisable to stick to
two-letter language codes.
- `default`: The default language to choose, if none is explicitly set using
`lang` or `setlanguage` (see below).
- `add_missing`: Whether or not to automatically add missing labels to the
translation file.
- `use_fallback`: Fallback to the 'default language', if the label is not
defined in the selected language? If set to `false` the extension will
return the untranslated label for display in the browser.
Permissions
-----------
To control which users can modify the labels, this extension uses Bolt's
built-in permission system. The labels configuration screen can not be accessed
by users without the `labels` permission. For any users other than those with
'root' roles, you'll need to add the permission to your `permissions.yml` file,
like this:
```yaml
global:
…
labels: [ admin, developer, chief-editor ]
…
```
Options for setting the language
--------------------------------
This extensions uses the lang parameter that can be set in a number of ways:
1. By passing it along in the request: `example.org?lang=nl`
2. By using the host name: `nl.example.org`
3. By prefixing a route [as explained in the docs](https://docs.bolt.cm/howto/building-multilingual-websites#defining-routes):
`example.org/nl/pages`
4. By extracting a value from a given locale "nl_NL" and checking whether this
is a defined value in the `languages` configuration
5. By using the default from the configuration file
6. By simply overriding all of these and setting the language in your twig
template files: `{{ setlanguage('de') }}`
Usage in templates
------------------
Basic usage: `{{ l('click here') }}`
Note: it's advisable to keep the _labels_ as well as the _language_ names as
lowercase. The actual translated labels are case sensitive, and will be used,
as they are provided in the translation table.
The label that is returned for output in the browser depends on the current
language setting. You can pass this explitly, using: `{{ l('click here', 'nl')
}}`, but it's usually preferable to set this once in the header of your
template.
```html
{{ setlanguage('fr') }}
..
{{ l('click here') }} -> returns label in french.
```
Likewise, you can retrieve the current language:
```html
{{ getlanguage() }}
```
When working on a website, it's probably easiest to just create the templates,
adding `{{ l('foo') }}` tags where applicable. If the `add_missing` option in
the config file is set, these will be added to the labels file automatically,
once they've been encountered in the templates. This allows you to work on the
templates, and then translate all of the labels at once.
If you're working on a larger site, it might be advisable to use a namespace-
like structure, to specify the context where a label is used. For example, this
would lead to confusion:
```html
To go to the frontpage, click {{ l('home') }}.
{{ l('home') }} is where the heart is.
```
These would be translated differently in most languages. As such, it's good to
prefix them with a 'namespace' to make the context clear. There are no set pre-
defined namespaces. Pick and choose whatever suits your project. For example:
```html
To go to the frontpage, click {{ l('navigation:home') }}.
{{ l('text:home') }} is where the heart is.
```
Tip: To modify the output of labels, you can use `capitalize`, `lower` and
`upper`. For example:
```html
{{ l('hello') }} -> hallo
{{ l('hello')|capitalize }} -> Hallo
{{ l('hello')|lower }} -> Hallo
{{ l('hello')|upper }} -> HALLO
```
Tip: Always keep a backup of the translation file. You never know what might
happen, and if it (for some reason) gets corrupted, it will be good to have a
recent backup available. By default the file is located at
`app/config/extensions/labels.json`.