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:
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 usinglangorsetlanguage(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 tofalsethe extension will return the untranslated label for display in the browser.
This extensions uses the lang parameter that can be set in a number of ways:
- By passing it along in the request:
example.org?lang=nl - By using the host name:
nl.example.org - By prefixing a route as explained in the docs:
example.org/nl/pages - By extracting a value from a given locale "nl_NL" and checking whether this
is a defined value in the
languagesconfiguration - By using the default from the configuration file
- By simply overriding all of these and setting it in the header of your twig
template files:
{% set lang = 'de' %}
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.
{{ setlanguage('fr') }}
..
{{ l('click here') }} -> returns label in french.
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:
<p>
To go to the frontpage, click <a href='/'>{{ l('home') }}</a>.
</p>
<p>
{{ l('home') }} is where the heart is.
</p>
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:
<p>
To go to the frontpage, click <a href='/'>{{ l('navigation:home') }}</a>.
</p>
<p>
{{ l('text:home') }} is where the heart is.
</p>
Tip: To modify the output of labels, you can use capitalize, lower and
upper. For example:
{{ 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.