Document translation

web/docs/README.md

@@ -1,4 +1,4 @@
-## Developer docs
+# Developer docs
 
 If you just want to run ente locally or develop on it, you can do
 

web/docs/dependencies.md

@@ -45,6 +45,8 @@ of React, but those are contingent and can be replaced, or even removed. But the
 usage of React is deep rooted. React also has a sibling "react-dom" package that
 renders "React" interfaces to the DOM.
 
+### MUI and Emotion
+
 Currently, we use MUI ("@mui/material"), which is a React component library, to
 get a base set of components. MUI uses Emotion (a styled-component variant) as
 its preferred CSS-in-JS library and to keep things simple, that's also what we
@@ -66,3 +68,18 @@ Emotion itself comes in many parts, of which we need the following three:
   > use it explicitly, it's a peer dependency of `@mui/material`.
 
 * "@emotion/server"
+
+### Translations
+
+For showing the app's UI in multiple languages, we use the i18next library,
+specifically its three components
+
+* "i18next": The core `i18next` library.
+* "i18next-http-backend": Adds support for initializing `i18next` with JSON file
+  containing the translation in a particular language, fetched at runtime.
+* "react-i18next": React specific support in `i18next`.
+
+Note that inspite of the "next" in the name of the library, it has nothing to do
+with Next.js.
+
+For more details, see [translations.md](translations.md).

web/docs/dev.md

@@ -1,3 +1,5 @@
+# Notes for Developers
+
 ## Monorepo
 
 The monorepo uses Yarn (classic) workspaces.

web/docs/new.md

@@ -1,4 +1,4 @@
-## Welcome!
+# Welcome!
 
 If you're new to this sort of stuff or coming back to it after mobile/backend
 development, here is a recommended workflow:
@@ -14,7 +14,7 @@ development, here is a recommended workflow:
 
 That's it. Enjoy coding!
 
-### Yarn
+## Yarn
 
 Note that we use Yarn classic
 

web/docs/translations.md

@@ -0,0 +1,45 @@
+# Translations
+
+We use Crowdin for translations, and the `i18next` library to load these at
+runtime.
+
+Within our project we have the _source_ strings - these are the key value pairs
+in the `public/locales/en-US/translation.json` file in each app.
+
+Volunteers can add a new _translation_ in their language corresponding to each
+such source key-value to our [Crowdin
+project](https://crowdin.com/project/ente-photos-web).
+
+Everyday, we run a [GitHub workflow](../../.github/workflows/web-crowdin.yml)
+that
+
+* Uploads sources to Crowdin - So any new key value pair we add in the source
+  `translation.json` becomes available to translators to translate.
+
+* Downloads translations from Crowdin - So any new translations that translators
+  have made on the Crowdin dashboard (for existing sources) will be added to the
+  corresponding `lang/translation.json`.
+
+The workflow also uploads existing translations and also downloads new sources
+from Crowdin, but these two should be no-ops.
+
+## Adding a new string
+
+- Add a new entry in `public/locales/en-US/translation.json` (the **source `translation.json`**).
+- Use the new key in code with the `t` function (`import { t } from "i18next"`).
+- During the next sync, the workflow will upload this source item to Crowdin's
+  dashboard, allowing translators to translate it.
+
+## Updating an existing string
+
+- Update the existing value for the key in the source `translation.json`.
+- During the next sync, the workflow will clear out all the existing
+  translations so that they can be translated afresh.
+
+## Deleting an existing string
+
+- Remove the key value pair from the source `translation.json`.
+- During the next sync, the workflow will delete that source item from all
+  existing translations (both in the Crowdin project and also from the he other
+  `lang/translation.json` files in the repository).
+