From a969e382199ab804d3cd600b608930503dc69caf Mon Sep 17 00:00:00 2001 From: Peter Hartshorn Date: Thu, 8 Dec 2022 12:12:21 +0000 Subject: [PATCH] Updates and improves documentation * Removes reference to duplicate plurals.rb file in govuk_app_config (now removed) * Updates `sed` command for deleting a key. The new previous command didn't work for me. Tested new command and seems to as expected. * Corrects typo in `perl` command: `nmany` -> `many` * Updates description for `remove_unsued` command and makes it more prominent --- docs/adding-editing-plural-forms.md | 19 ++++++++++--------- docs/rake-command-reference.md | 12 +++++++++++- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/adding-editing-plural-forms.md b/docs/adding-editing-plural-forms.md index e0f4e6f..2d13d2c 100644 --- a/docs/adding-editing-plural-forms.md +++ b/docs/adding-editing-plural-forms.md @@ -1,25 +1,24 @@ # Adding a language's plural form -We maintain our own [plurals.rb](https://github.com/alphagov/rails_translation_manager/blob/master/config/locales/plurals.rb) configuration file. If adding a language to Rails Translation Manager, that doesn't exist in [rails-i18n](https://github.com/svenfuchs/rails-i18n), you may need to edit this file. +We maintain our own [plurals.rb][1] configuration file. This is used for plural +rules that don't exist in [rails-i18n][2]. -This config is needed to correctly distinguish the [plural rules](https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html) for locales not included in `rails-i18n`, as it is needed for plural validation checks. - -Note that there is currently a [duplicate list in `govuk_app_config](https://github.com/alphagov/govuk_app_config/blob/main/lib/govuk_app_config/govuk_i18n.rb). The intention is for this to be removed and for the Rails Translation Manager version to be the sole version. +If there is a missing plural rule (fails plural validator) then we can add the +rule to our [plurals.rb][1] file. Plural rules for most languages can be found +on the [unicode website][3] (cardinal type). ## Editing plural forms Keys with incorrect plural forms are more complex to adjust. If there are keys with additional unnecessary plural forms, they can be deleted: ``` -sed -i '' '/^ \+one:/d' config/locales/xx.yml +sed -i '' '/^ *one:/d' config/locales/xx.yml ``` -This commonly occurs for e.g. Chinese and Vietnamese which are expected to have only an `:other` and not a `:one` form. - Keys which need a plural form added can be automated with caution. If every key of a specific translation needs the new plural added, it can be done by adding a blank key before every `other:` key: ``` -perl -0777 -p -i -e 's/\n(\s+)other:/\n\1nmany:\n\1other:/g' config/locales/xx.yml +perl -0777 -p -i -e 's/\n(\s+)other:/\n\1many:\n\1other:/g' config/locales/xx.yml ``` Or if only a specific key needs the plural added: @@ -28,4 +27,6 @@ Or if only a specific key needs the plural added: perl -0777 -p -i -e 's/(key_with_missing_plural:\n)(\s+)/\1\2zero:\n\2/g' config/locales/xx.yml ``` -This commonly occurs for Slavic languages and Arabic, for example, which have plural forms other than just `:one` and `:other`. +[1]: https://github.com/alphagov/rails_translation_manager/blob/main/config/locales/plurals.rb +[2]: https://github.com/svenfuchs/rails-i18n +[3]: https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html diff --git a/docs/rake-command-reference.md b/docs/rake-command-reference.md index 107cfe3..9e97170 100644 --- a/docs/rake-command-reference.md +++ b/docs/rake-command-reference.md @@ -42,11 +42,21 @@ rake translation:normalize Remove keys that are not used anywhere in your application: +**Warning**: +> Removing unused keys may remove keys that actually _are_ used by your + application. This happens when RTM fails to scan certain keys in the + codebase, e.g when the keys are referenced dynamically. You can make RTM + ignore these keys by creating a `/config/i18n-tasks.yml` file with an + `ignore_unused` key. + + A safer way to remove known unused keys is to use the [Delete keys](https://github.com/glebm/i18n-tasks#delete-keys) + command. + ``` rake translation:remove_unused ``` -Sometimes RTM might remove keys that actually _are_ used by your application. This happens when the keys are referenced dynamically. You can make RTM ignore these keys by creating a `/config/i18n-tasks.yml` file with an `ignore_unused` key. For example: +Example `ignore_unused` config: ```yaml ignore_unused: