make README more welcoming
This commit is contained in:
parent
db54e1a3b0
commit
3119e3a4cf
110
README.md
110
README.md
|
|
@ -1,3 +1,111 @@
|
|||
# ansible-callback-i18n
|
||||
|
||||
An Ansible callback plugin to support a simple translations system (i18n)
|
||||
This [callback plugin](https://docs.ansible.com/ansible/latest/plugins/callback.html) for Ansible proposes translations for plays/tasks. It is forked from the **excellent** [dense](https://docs.ansible.com/ansible/latest/plugins/callback/dense.html) plugin by Dag Wieers (@dagwieers).
|
||||
|
||||
# Setup
|
||||
|
||||
On Debian stable, once ansible is setup, you simply need to copy the i18n.py file to ansible's plugins/callback directory:
|
||||
|
||||
```
|
||||
$ git clone https://tildegit.org/southerntofu/ansible-i18n
|
||||
$ sudo cp ansible-i18n/i18n.py /usr/lib/python3/dist-packages/ansible/plugins/callback/
|
||||
```
|
||||
|
||||
Now that the plugin is setup (yes, that was it), you may want to configure Ansible to use it. To use the plugin for a single run, you can use the [ANSIBLE_STDOUT_CALLBACK](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-stdout-callback) environment variable:
|
||||
|
||||
```
|
||||
$ ANSIBLE_STDOUT_CALLBACK=i18n ansible-playbook -i hosts playbook.yml
|
||||
```
|
||||
|
||||
If you want to use the plugin for the whole project, you can set it in the project's root in an ansible.cfg file:
|
||||
|
||||
```
|
||||
[defaults]
|
||||
stdout_callback = i18n
|
||||
```
|
||||
|
||||
Additionally, if you want to use the plugin for all projects, you can set it in ~/.ansible.cfg (user setting) or /etc/ansible/ansible.cfg (system setting).
|
||||
|
||||
**NOTE:** If you're using the `ansible` command and not `ansible-playbook`, you need to either set `bin_ansible_callbacks` field to true in the config, or use the ANSIBLE_LOAD_CALLBACKS_PLUGINS=1 environment variale.
|
||||
|
||||
# Using
|
||||
|
||||
When initializing the plugins, it will look for the i18n folder in your current directory. If it exists, it will load the files in there as separate languages: `i18n/fr.yml` for french, `i18n/en.yml` for english, etc. If the folder does not exist or is empty, no translation is used at all.
|
||||
|
||||
Once the languages are loaded, the plugin will lookup your current locale through the LANG environment variable. The first two characters are extracted, and if they match a language in the translations, this language is used. If the locale doesn't match a known language :
|
||||
|
||||
- if there is only one language found in the i18n folder, it is used
|
||||
- otherwise, no translation is used (what, would you like me to randomly pick a language?)
|
||||
|
||||
For each operation type, status and name, the plugin will look for a key in the current language. If this translated key does not exist, the key name itself is used. THis means if your language is only partially translated, you will not get the full experience but it should not blow up in your face.
|
||||
|
||||
In summary, if you want to translate a task called "Setup web server" in french, place the following line in `i18n/fr.yml`:
|
||||
|
||||
```
|
||||
Setup web server: Installer le serveur web
|
||||
```
|
||||
|
||||
# Translating
|
||||
|
||||
To get started, you need only a few lines. Here's what i used for a sample i18n/fr.yml:
|
||||
|
||||
```
|
||||
SUMMARY: RÉSUMÉ
|
||||
ok: ok
|
||||
changed: changéE
|
||||
ignored: ignoré
|
||||
failed: échoué
|
||||
unreachable: injoignable
|
||||
task: Tâche
|
||||
handler: Gestionnaire
|
||||
Gathering Facts: Rassembler les faits
|
||||
```
|
||||
|
||||
Then, as you add task/play names don't forget to translate them.
|
||||
|
||||
# Example
|
||||
|
||||
An example playbook.yml is provided in this repository for demo purposes. You can run it like this:
|
||||
|
||||
```
|
||||
# Following your locale
|
||||
$ ansible-playbook --connection=local --inventory 127.0.0.1, --limit 127.0.0.1 playbook.yml
|
||||
# In french
|
||||
$ LANG=fr ansible-playbook --connection=local --inventory 127.0.0.1, --limit 127.0.0.1 playbook.yml
|
||||
```
|
||||
|
||||
# FAQ
|
||||
|
||||
## How do i use a default language as fallback?
|
||||
|
||||
Short answer: Define the LANG environment variable properly. If you need to do it for one command only, then just type `LANG=fr` before your ansible command.
|
||||
|
||||
If you really want to have a default language, you can simply write your task/play names in this language, and if they don't have translations, they won't be translated. However, this is **strongly discouraged** because if you do that, simply changing your task name will break existing translations!
|
||||
|
||||
## Can it break something?
|
||||
|
||||
It should not. If a translation is not found, the standard (untranslated) name is used instead. If something breaks by using this plugin, it's a bug so please report it.
|
||||
|
||||
## How do i debug things?
|
||||
|
||||
The usual ansible flags -v and -vvv apply. -v will provide more information on what's changed. -vvv will run the debug output and so no translation will be applied.
|
||||
|
||||
## Nice term tricks, how did you do?
|
||||
|
||||
I didn't. All the super sweet stuff found in this repo was built by @dagwieers so huge thanks to this person for saving me from information overdose.
|
||||
|
||||
## Is this plugin feature-complete?
|
||||
|
||||
This plugin works for me. I hope it helps other people as well. Patches are welcome, but i don't want to maintain a complicated plugin so if that's your project don't hesitate to fork.
|
||||
|
||||
There's still a few TODO to print format error messages properly. This is the case for:
|
||||
|
||||
- line 179: YAMLError when loading translation files
|
||||
- line 193 and 199: we should print a warning when the languaged defined in the locale was not found
|
||||
|
||||
## What license is it?
|
||||
|
||||
This is GPLv3+ software, because :
|
||||
|
||||
- copyleft is pretty cool (fuck private property, share everything)
|
||||
- the original code is GPLv3+ so please don't argue
|
||||
|
|
|
|||
Loading…
Reference in New Issue