chore: add translation keys guidelines (nodejs#5279)

Co-authored-by: Shanmughapriyan S <[email protected]>
Co-authored-by: Michael Esteban <[email protected]>

Author: 3 people

TRANSLATION.md

@@ -8,7 +8,7 @@ Node.js is a global platform and so this site has many translations. The transla
 2. [Select the language you want to translate](https://support.crowdin.com/joining-translation-project/#starting-translation)
 3. [Start translating](https://support.crowdin.com/online-editor/)
 
-## Any questions or feedbacks on Translations
+### Any questions or feedbacks on Translations
 
 If you have any questions or feedbacks on current translations, you can [start a discussion](https://crowdin.com/project/nodejs-website/discussions) by choosing the "New Topic" and your language from the right dropdown, or a [conversation](https://support.crowdin.com/conversations/) by adding your translators.
 
@@ -39,3 +39,23 @@ Fill the language object with the following fields:
 | `dateFormat` | The date format. It must be a valid [moment.js format](https://momentjs.com/docs/#/displaying/format/) | `DD.MM.YYYY` |
 | `hrefLang`   | The language code in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format         | `fr`         |
 | `enabled`    | If the language is enabled or not                                                                      | `true`       |
+
+## Adding new Translation Keys
+
+If you're making a new Component and adding Translation Keys for your Component, they should follow these guidelines:
+
+- Only add the new translation keys on the `i18n/locales/en.json` file. Crowdin will handle on syncing the files and letting translators know there are new keys to be translated
+- The translation keys should have the prefix as the canonical path of your Component. If your Component is `components/Common/MyComponent` the prefix key should be `components.common.myComponent`
+  - The Translation Key suffix should be easy to undersand and semantic. For example, if the key is about "the text of a button that when interacted it copies content to the clipboard", the suffix should probably be `copyButton.title`. The final translation key would be `components.common.myComponent.copyButton.title`
+  - Translation Keys should be in Camel Case only.
+  - The values of each Translation Key should follow the [ICU Message Syntax](https://formatjs.io/docs/core-concepts/icu-syntax/)
+- All new Translation keys should be added at the bottom of the `i18n/locales/en.json` file. Since this makes it easer for Translators to notice that there are new Translation keys to be translated.
+
+### Translations and Unit Testing
+
+Translation Keys should not be translated during Unit Testing. If your Component uses, for example `FormattedMessage`, you should provide the `<IntlProvider>` surrounding your `testing-library` render logic. Or, you can create a wrapper for your test. Note that you should not import the English messages to your Unit Test as:
+
+- Unit Testing should test a Component functionality.
+- Unit Tests should not rely on text, titles, or string bags, as these texts will change arbitrarily and make the test suite fail.
+  - In this case, you should test your component by aria-text, or other `aria-*` attributes or even by class names or other artifacts.
+- If you want to test how different languages and text appear within a Component, Visual Regression Testing is recommended.