Add latest changes from gitlab-org/gitlab@master

1 files changed, 15 insertions, 0 deletions

diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index abdaa681230..78caac0d6d5 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.