Merge pull request #3444 from Expensify/ionatan_i18nreadme

README.md

@@ -15,6 +15,7 @@
 * [Debugging](#debugging)
 * [Structure of the app](#structure-of-the-app)
 * [Philosophy](#Philosophy)
+* [Internationalization](#Internationalization)
 * [Deploying](#deploying)
 
 #### Additional Reading
@@ -236,6 +237,32 @@ This application is built with the following principles.
 
 ----
 
+# Internationalization
+This application is built with Internationalization (I18n) / Localization (L10n) support, so it's important to always 
+localize the following types of data when presented to the user (even accessibility texts that are not rendered):
+
+- Texts: See [translate method](https://github.com/Expensify/Expensify.cash/blob/655ba416d552d5c88e57977a6e0165fb7eb7ab58/src/libs/translate.js#L15) 
+- Date/time: see [DateUtils](https://github.com/Expensify/Expensify.cash/blob/f579946fbfbdc62acc5bd281dc75cabb803d9af0/src/libs/DateUtils.js)
+- Numbers and amounts: see [numberFormat](https://github.com/Expensify/Expensify.cash/tree/965f92fc2a5a2a0d01e6114bf5aa8755b9d9fd1a/src/libs/numberFormat)
+- Phones: see [LocalPhoneNumber](https://github.com/Expensify/Expensify.cash/blob/bdfbafe18ee2d60f766c697744f23fad64b62cad/src/libs/LocalePhoneNumber.js#L51-L52)
+
+In most cases, you will be needing to localize data used in a component, if that's the case, there's a HOC [withLocalize](https://github.com/Expensify/Expensify.cash/blob/37465dbd07da1feab8347835d82ed3d2302cde4c/src/components/withLocalize.js).
+It will abstract most of the logic you need (mostly subscribe to the [PREFERRED_LOCALE](https://github.com/Expensify/Expensify.cash/blob/6cf1a56df670a11bf61aa67eeb64c1f87161dea1/src/ONYXKEYS.js#L88) Onyx key)
+and is the preferred way of localizing things inside components.
+
+Some pointers:
+
+- All translations are stored in language files in [src/languages](https://github.com/Expensify/Expensify.cash/tree/b114bc86ff38e3feca764e75b3f5bf4f60fcd6fe/src/languages).
+- We try to group translations by their pages/components
+- A common rule of thumb is to move a common word/phrase to be shared when it's in 3 places
+- Always prefer longer and more complex strings in the translation files. For example 
+  if you need to generate the text `User has sent $20.00 to you on Oct 25th at 10:05am`, add just one
+  key to the translation file and use the arrow function version, like so:
+  `nameOfTheKey: ({amount, dateTime}) => "User has sent " + amount + " to you on " + dateTime,`.
+  This is because the order of the phrases might vary from one language to another.
+
+----
+
 # Deploying
 ## QA and deploy cycles
 We utilize a CI/CD deployment system built using [GitHub Actions](https://github.com/features/actions) to ensure that new code is automatically deployed to our users as fast as possible. As part of this process, all code is first deployed to our staging environments, where it undergoes quality assurance (QA) testing before it is deployed to production. Typically, pull requests are deployed to staging immediately after they are merged.