From c4ac455fb8822cf90507eb160b5a948071bd41e9 Mon Sep 17 00:00:00 2001
From: Lidiane Taquehara <lidi.mayra@gmail.com>
Date: Fri, 22 Jul 2022 16:40:14 +0200
Subject: [PATCH] Include docs about i18n

We setup react-i18next during
[these changes](https://github.com/artsy/force/pull/9797), these docs
contain instructions about the context, usage and next steps.

Co-authored-by: Lidiane Taquehara <lidi.mayra@gmail.com>
Co-authored-by: Leandro Linares <leandro.linares@artsymail.com>
---
 docs/i18n.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/i18n.md

diff --git a/docs/i18n.md b/docs/i18n.md
new file mode 100644
index 00000000000..3d418588512
--- /dev/null
+++ b/docs/i18n.md
@@ -0,0 +1,91 @@
+# i18n
+
+## Context
+
+Internationalization on Force was introduced as a hackathon project ([PR](https://github.com/artsy/force/pull/9797)).
+
+We are using the [react-i18next](https://react.i18next.com/) internationalization framework for this.
+
+The goal of these change is separating the text content from the codebase, so copy updates can handled in a smoother process.
+
+See [this
+presentation](https://docs.google.com/presentation/d/1VT44uoGAaHX0EcDaYwGHiY8VU-fAkOXK6rSHto/edit#slide=id.gd1b1ff661f_0_12) about the benefits we expect to achieve.
+
+## How to
+
+Locales are defined on [src/System/locales](https://github.com/artsy/force/tree/main/src/System/locales). Currently, the only language supported is en-US.
+
+### Importing react-i18next
+
+1. Import the library:
+
+```jsx
+import { useTranslation } from "react-i18next”
+```
+
+2. Use the `useTranslation` hook on functional components:
+
+```jsx
+const { t } = useTranslation()
+```
+
+### Adding a static string
+
+1. Add the string to [translation.json](https://github.com/artsy/force/blob/main/src/System/locales/en-US/translation.json) following the Naming conventions.
+2. Use it in any component by calling `{t`<path-for-the-key>`}` (example: `{t`navbar.shows`}`)
+
+### Adding a dynamic string
+
+You can use [interpolation](https://www.i18next.com/translation-function/interpolation) in case you need to pass dynamic values
+
+1. Add a string to translation.json defining the keys (example: `"greetings": "hello {{name}}"`)
+2. When calling it in a component, pass the dynamic values as keys (example: `{t('hello', { name: 'John')}`)
+
+### Working with class components
+
+In some scenarios, we'll need to pass the `t` function as an argument to another function.
+We can do this by using the [ClassI18n](https://github.com/artsy/force/blob/main/src/System/i18n/ClassI18n.tsx) class.
+See an example of usage on the [SearchBar](https://github.com/artsy/force/blob/main/src/Components/Search/SearchBar.tsx). As the
+`Form` component is wrapped inside `ClassI18n` , it is capable of passing the `t` function as an argument to the `renderAutosuggestComponent` function.
+
+### Naming conventions for translations keys
+
+We always use:
+
+- The name of the component followed by the key definition in dot notation;
+- lowerCamelCase;
+- Short definitions: maximum length of 5 words;
+
+For translations used in several spots, we might want to create a `shared` namespace.
+
+## Further improvements
+
+### Serve static assets on the server-side
+
+Our translations files are separated according to locales. If at some point, we want to include new
+locales, we don't want all files associated to locales to be loaded when accessing Artsy. Ideally,
+we want to serve those assets on the server-side (possibly uploading it to AWS) and consume only the
+ones that make sense given the context of the current request.
+
+### Set up a third-party service for translations management
+
+We would like our translations to be synced with a third-party tool, enabling translations
+management to happen through a friendly interface, making the process easier for UX writers,
+designers and PMs.
+
+See [this comparison
+table](https://docs.google.com/spreadsheets/d/1NtcqofHLG17TPgYQ2G5C1X5aFHa95qAVTyjqa78joJo/edit#gid=0)
+regarding the main alternatives considered so far.
+
+### Use `en` locale as "dev english"
+
+For the initial setup, we are supporting translations on `en-US` locale. Ideally, we would like to
+use `en` locale as development locale, one that we can use to set the root version of every string,
+but the website will actually use the `en-US` version, the one to be maintained by different teams
+at Artsy. Using a third-party service, the suggested flow would be:
+
+1. Engineers open a PR to main containing the keys in the root `locale` assigning to it a default
+   value
+2. Once the PR is merged, it synchronizes with the third-party service
+3. `en-US` is updated there and a PR is automatically opened to the repository on GitHub
+4. The PR is merged by an Engineer so the project will include the updated locales