diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index abdaa6812309865b5bc1e27308468f975433aac6..78caac0d6d51c9e3e14c796bcd1fc9a98aa8f888 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -480,6 +480,21 @@ This makes use of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/do ## Best practices +### Minimize translation updates + +Updates can result in the loss of the translations for this string. To minimize risks, +avoid changes to strings, unless they: + +- Add value to the user. +- Include extra context for translators. + +For example, we should avoid changes like this: + +```diff +- _('Number of things: %{count}') % { count: 10 } ++ n_('Number of things: %d', 10) +``` + ### Keep translations dynamic There are cases when it makes sense to keep translations together within an array or a hash.