Internationalization & localization

babel.config.js

@@ -45,6 +45,7 @@ module.exports = function (api) {
           },
         },
       ],
+      'macros',
       'react-native-reanimated/plugin', // NOTE: this plugin MUST be last
     ],
     env: {

docs/internationalization.md

@@ -0,0 +1,113 @@
+# Internationalization
+
+We want the official Bluesky app to be supported in as many languages as possible. If you want to help us translate the app, please open a PR or issue on the [Bluesky app repo on GitHub](https://github.com/bluesky-social/social-app)
+
+## Tools
+We are using Lingui to manage translations. You can find the documentation [here](https://lingui.dev/).
+
+### Adding new strings
+When adding a new string, do it as follows:
+```jsx
+// Before
+import { Text } from "react-native";
+
+<Text>Hello World</Text>
+```
+
+```jsx
+// After
+import { Text } from "react-native";
+import { Trans } from "@lingui/macro";
+
+<Text><Trans>Hello World</Trans></Text>
+```
+
+The `<Trans>` macro will extract the string and add it to the catalog. It is not really a component, but a macro. Further reading [here](https://lingui.dev/ref/macro.html)
+
+However sometimes you will run into this case:
+```jsx
+// Before
+import { Text } from "react-native";
+
+const text = "Hello World";
+<Text accessibilityLabel="Label is here">{text}</Text>
+```
+In this case, you cannot use the `useLingui()` hook:
+```jsx
+import { msg } from "@lingui/macro";
+import { useLingui } from "@lingui/react";
+
+const { _ } = useLingui();
+return <Text accessibilityLabel={_(msg`Label is here`)}>{text}</Text>
+```
+
+If you want to do this outside of a React component, you can use the `t` macro instead (note: this won't react to changes if the locale is switched dynamically within the app):
+```jsx
+import { t } from "@lingui/macro";
+
+const text = t`Hello World`;
+```
+
+We can then run `yarn intl:extract` to update the catalog in `src/locale/locales/{locale}/messages.po`. This will add the new string to the catalog.
+We can then run `yarn intl:compile` to update the translation files in `src/locale/locales/{locale}/messages.js`. This will add the new string to the translation files. 
+The configuration for translations is defined in `lingui.config.js`
+
+So the workflow is as follows:
+1. Wrap messages in Trans macro
+2. Run `yarn intl:extract` command to generate message catalogs
+3. Translate message catalogs (send them to translators usually)
+4. Run `yarn intl:compile` to create runtime catalogs
+5. Load runtime catalog
+6. Enjoy translated app!
+
+### Common pitfalls
+These pitfalls are memoization pitfalls that will cause the components to not re-render when the locale is changed -- causing stale translations to be shown.
+
+```jsx
+import { msg } from "@lingui/macro";
+import { i18n } from "@lingui/core";
+
+const welcomeMessage = msg`Welcome!`;
+
+// ❌ Bad! This code won't work
+export function Welcome() {
+  const buggyWelcome = useMemo(() => {
+    return i18n._(welcomeMessage);
+  }, []);
+
+  return <div>{buggyWelcome}</div>;
+}
+
+// ❌ Bad! This code won't work either because the reference to i18n does not change
+export function Welcome() {
+  const { i18n } = useLingui();
+
+  const buggyWelcome = useMemo(() => {
+    return i18n._(welcomeMessage);
+  }, [i18n]);
+
+  return <div>{buggyWelcome}</div>;
+}
+
+// ✅ Good! `useMemo` has i18n context in the dependency
+export function Welcome() {
+  const linguiCtx = useLingui();
+
+  const welcome = useMemo(() => {
+    return linguiCtx.i18n._(welcomeMessage);
+  }, [linguiCtx]);
+
+  return <div>{welcome}</div>;
+}
+
+// 🤩 Better! `useMemo` consumes the `_` function from the Lingui context
+export function Welcome() {
+  const { _ } = useLingui();
+
+  const welcome = useMemo(() => {
+    return _(welcomeMessage);
+  }, [_]);
+
+  return <div>{welcome}</div>;
+}
+```

lingui.config.js

@@ -0,0 +1,11 @@
+/** @type {import('@lingui/conf').LinguiConfig} */
+module.exports = {
+  locales: ['en', 'cs', 'fr', 'hi', 'es'],
+  catalogs: [
+    {
+      path: '<rootDir>/src/locale/locales/{locale}/messages',
+      include: ['src'],
+    },
+  ],
+  format: 'po',
+}

package.json

@@ -28,7 +28,9 @@
     "perf:test:measure": "NODE_ENV=test flashlight test --bundleId xyz.blueskyweb.app --testCommand 'yarn perf:test' --duration 150000 --resultsFilePath .perf/results.json",
     "perf:test:results": "NODE_ENV=test flashlight report .perf/results.json",
     "perf:measure": "NODE_ENV=test flashlight measure",
-    "build:apk": "eas build -p android --profile dev-android-apk"
+    "build:apk": "eas build -p android --profile dev-android-apk",
+    "intl:extract": "lingui extract",
+    "intl:compile": "lingui compile"
   },
   "dependencies": {
     "@atproto/api": "^0.6.23",
@@ -42,6 +44,7 @@
     "@fortawesome/free-solid-svg-icons": "^6.1.1",
     "@fortawesome/react-native-fontawesome": "^0.3.0",
     "@gorhom/bottom-sheet": "^4.5.1",
+    "@lingui/react": "^4.5.0",
     "@mattermost/react-native-paste-input": "^0.6.4",
     "@miblanchard/react-native-slider": "^2.3.1",
     "@react-native-async-storage/async-storage": "1.18.2",
@@ -164,10 +167,12 @@
   },
   "devDependencies": {
     "@atproto/dev-env": "^0.2.5",
-    "@babel/core": "^7.20.0",
+    "@babel/core": "^7.23.2",
     "@babel/preset-env": "^7.20.0",
     "@babel/runtime": "^7.20.0",
     "@did-plc/server": "^0.0.1",
+    "@lingui/cli": "^4.5.0",
+    "@lingui/macro": "^4.5.0",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.5.11",
     "@react-native-community/eslint-config": "^3.0.0",
     "@testing-library/jest-native": "^5.4.1",
@@ -192,6 +197,7 @@
     "@typescript-eslint/parser": "^5.48.2",
     "babel-jest": "^29.4.2",
     "babel-loader": "^9.1.2",
+    "babel-plugin-macros": "^3.1.0",
     "babel-plugin-module-resolver": "^5.0.0",
     "babel-plugin-react-native-web": "^0.18.12",
     "detox": "^20.13.0",

src/App.web.tsx

@@ -16,6 +16,9 @@ import {Shell} from 'view/shell/index'
 import {ToastContainer} from 'view/com/util/Toast.web'
 import {ThemeProvider} from 'lib/ThemeContext'
 import {queryClient} from 'lib/react-query'
+import {i18n} from '@lingui/core'
+import {I18nProvider} from '@lingui/react'
+import {defaultLocale, dynamicActivate} from './locale/i18n'
 import {Provider as ShellStateProvider} from 'state/shell'
 import {Provider as ModalStateProvider} from 'state/modals'
 import {Provider as MutedThreadsProvider} from 'state/muted-threads'
@@ -34,6 +37,7 @@ const InnerApp = observer(function AppImpl() {
       setRootStore(store)
       analytics.init(store)
     })
+    dynamicActivate(defaultLocale) // async import of locale data
   }, [])
 
   // show nothing prior to init
@@ -47,9 +51,11 @@ const InnerApp = observer(function AppImpl() {
         <RootSiblingParent>
           <analytics.Provider>
             <RootStoreProvider value={rootStore}>
-              <SafeAreaProvider>
-                <Shell />
-              </SafeAreaProvider>
+              <I18nProvider i18n={i18n}>
+                <SafeAreaProvider>
+                  <Shell />
+                </SafeAreaProvider>
+              </I18nProvider>
               <ToastContainer />
             </RootStoreProvider>
           </analytics.Provider>

src/locale/i18n.ts

@@ -0,0 +1,20 @@
+import {i18n} from '@lingui/core'
+
+export const locales = {
+  en: 'English',
+  cs: 'Česky',
+  fr: 'Français',
+  hi: 'हिंदी',
+  es: 'Español',
+}
+export const defaultLocale = 'en'
+
+/**
+ * We do a dynamic import of just the catalog that we need
+ * @param locale any locale string
+ */
+export async function dynamicActivate(locale: string) {
+  const {messages} = await import(`./locales/${locale}/messages`)
+  i18n.load(locale, messages)
+  i18n.activate(locale)
+}