diff --git a/i18n.md b/i18n.md index 3924e70..ce2daeb 100644 --- a/i18n.md +++ b/i18n.md @@ -28,12 +28,43 @@ tx pull --force ## Development -### Clear cache after translation changes +You are welcome to fix typos, add missing translations and remove unused ones in `config/locales/en.yml`. Don't change the other locales as that creates conflicts with our Transifex integration described above. -When making changes to `config/locales/en.yml` or other locals, ensure you reload I18n js translations to see the changes in the application. -``` -rake tmp:cache:clear -``` +Here are some guidelines to make sure that the source locale file `en.yml` is becoming more beautiful +with every change we do. + +* Change text: No problem. Fix the typo. And please enclose the text in quotes + to avoid any accidents. + + - `example_1: "When you're using double quotes, they look like \"this\""` + - `example_2: "When you’re using double quotes, they look like “this”"` + + The second example uses unicode to make it look prettier and avoid backslashes. + +* Add translations: Cool, every bit of text in the application should be here. + If you add a translation for a view or mailer, please make use of the nested + structure. Use the "lazy" lookup. See: http://guides.rubyonrails.org/i18n.html#looking-up-translations + + Avoid global keys. There are a lot already. And some are okay, for example + "enterprises" should be the same everywhere on the page. But in doubt, + create a new translation and give it a meaningful scope. + + Don't worry about duplication. We may use the same word in different contexts, + but another language could use different words. So don't try to re-use + translations between files. + + Don't move big parts around or rename scopes with a lot of entries without + a really good reason. In some cases that causes a lot of translations in + other languages to be lost. That causes more work for translators. + +* Remove translations: Be careful. If you are sure that a translation is not used anywhere, + please remove them. But be aware that some translations are looked up with + variables. For example https://github.com/openfoodfoundation/openfoodnetwork/blob/deb04c3075e35a1d839b58206a5363dd99e1403d/app/views/admin/contents/_fieldset.html.haml#L6 looks + up labels for preferences. Unfortunately, they don't have a scope. + + It's also possible that the look up is in a gem. We still use a lot of Spree's views. So just because you can't find a translation key in the OFN code, it doesn't mean that the translation is not needed. + +There are also some common problems people run into described in the next sections. ### Scopes must be unique @@ -70,6 +101,13 @@ Good: In some cases we had problems with the global `t` function not working when called directly. I think it depends on the scope in which the code is running. Using the `t` filter is the safer option and we should try to be consistently using only that one in JavaScript. +### Clear cache after translation changes + +When making changes to `config/locales/en.yml` or other locals, ensure you reload I18n js translations to see the changes in the application. +``` +rake tmp:cache:clear +``` + ## Further reading * [Transifex Maintainers and Governance](https://community.openfoodnetwork.org/t/transifex-maintainers-and-governance/867)