diff --git a/docs/translating-dev.md b/docs/translating-dev.md index 6a7ff397be..ec54a4a53b 100644 --- a/docs/translating-dev.md +++ b/docs/translating-dev.md @@ -45,6 +45,7 @@ We are aiming for a set of common strings to be shared then some more localised 3. Keys for common accessibility strings must start by `a11y_`. Example: `a11y_hide_password` 4. Otherwise, try to group keys logically and nest where appropriate, such as `keyboard_` for strings relating to keyboard shortcuts. 5. Ensure your translation keys do not include `.` or `|` or ` `. Try to balance string length against descriptiveness. +6. Key names should match the meaning and purpose of the translations as closely as they can. E.g. "button_click_biscuits" -> "Click for biscuits" ## Adding new strings @@ -53,11 +54,17 @@ We are aiming for a set of common strings to be shared then some more localised 1. Run `pnpm i18n` to add the keys to `src/i18n/strings/en_EN.json` 1. Modify the new entries in `src/i18n/strings/en_EN.json` with the English (UK) translations for the added keys. -## Editing existing strings +## Editing non-English UK existing strings -Edits to existing strings should be performed only via Localazy. +Edits to existing **non-en_EN** strings should be performed only via Localazy. There you can also require all translations to be redone if the meaning of the string has changed significantly. +### Editing English UK (en_EN) strings + +Edits to `en_EN.json` **require** a PR, since there is a high chance that a test covers the string in use and may be impacted if it were to change. This also gives us a clean change history. + +When changing a string, be careful to rename the key if the meaning changes. For instance, if the key `button_click_biscuits` changed from "Click for biscuits" to "Click for vegetables", then they key should have changed to `button_click_vegetables`. + ## Removing existing strings You can remove an existing string by removing the key from `en_EN.json`. Do not modify other language json files for this purpose.