From 3da57f3892b7ef54e7603148199a762a5f38072a Mon Sep 17 00:00:00 2001 From: Vojtech Novak Date: Sun, 8 Sep 2024 20:39:55 +0200 Subject: [PATCH] docs: update docs --- website/docs/ref/cli.md | 5 +- website/docs/ref/loader.md | 2 +- website/docs/ref/metro-transformer.mdx | 103 +++++++++++++++++++++++++ website/docs/tutorials/react-native.md | 3 +- website/sidebars.ts | 5 ++ 5 files changed, 113 insertions(+), 5 deletions(-) create mode 100644 website/docs/ref/metro-transformer.mdx diff --git a/website/docs/ref/cli.md b/website/docs/ref/cli.md index 526d979fe..4f95de963 100644 --- a/website/docs/ref/cli.md +++ b/website/docs/ref/cli.md @@ -57,8 +57,7 @@ lingui extract [files...] [--locale ] [--convert-from ] [--verbose] - [--watch] - [--debounce ] + [--watch [--debounce ]] ``` The `extract` command looks for messages in the source files and extracts them @@ -211,7 +210,7 @@ One drawback to checking for missing translations is that the English message ca ## Catalogs in VCS and CI -If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](/docs/ref/loader.md) or [Vite plugin](/docs/ref/vite-plugin.md). +If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](/docs/ref/loader.md), [Vite plugin](/docs/ref/vite-plugin.md) or [Metro transformer](/docs/ref/metro-transformer.mdx). Depending on your localization setup, you might also want to run the `extract` command in CI and upload the extracted messages to a [translation service](/docs/tools/introduction.md). diff --git a/website/docs/ref/loader.md b/website/docs/ref/loader.md index 42c5104a9..c87185e8c 100644 --- a/website/docs/ref/loader.md +++ b/website/docs/ref/loader.md @@ -1,6 +1,6 @@ # Webpack Loader -The Webpack loader compiles catalogs on the fly. It replaces the `lingui compile` command: with the loader, you can `import` po files directly, instead of running `lingui compile` and `import`ing its output. +The Webpack loader compiles catalogs on the fly. It's an alternative to the [`lingui compile`](/ref/cli#compile) command: the loader enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files. ## Installation diff --git a/website/docs/ref/metro-transformer.mdx b/website/docs/ref/metro-transformer.mdx new file mode 100644 index 000000000..242876d1b --- /dev/null +++ b/website/docs/ref/metro-transformer.mdx @@ -0,0 +1,103 @@ +# Metro transformer + +[Metro bundler](https://metrobundler.dev/) is a JavaScript bundler used in React Native apps. This package offers an alternative to the [`lingui compile`](/ref/cli#compile) command: a transformer that enables Metro to compile `.po` files on the fly. The transformer enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files. + +## Installation + +> Only Expo SDK 49 and React Native v0.72.1 or newer are supported. + +Install `@lingui/metro-transformer` as a development dependency: + +```bash npm2yarn +npm install --save-dev @lingui/metro-transformer +``` + +Set up the transformer in your `metro.config.js` by specifying [`babelTransformerPath`](https://metrobundler.dev/docs/configuration/#babeltransformerpath) and updating `sourceExts`: + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + + + +```js title="metro.config.js" +// Learn more https://docs.expo.io/guides/customizing-metro +const { getDefaultConfig } = require("expo/metro-config"); + +const config = getDefaultConfig(__dirname); +const { transformer, resolver } = config; + +config.transformer = { + ...transformer, + babelTransformerPath: require.resolve("@lingui/metro-transformer/expo"), +}; +config.resolver = { + ...resolver, + sourceExts: [...resolver.sourceExts, "po", "pot"], +}; + +module.exports = config; +``` + + + + +```js title="metro.config.js" +const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config"); + +const defaultConfig = getDefaultConfig(__dirname); +const { assetExts, sourceExts } = defaultConfig.resolver; + +/** + * Metro configuration + * https://reactnative.dev/docs/metro + * + * @type {import('metro-config').MetroConfig} + */ +const config = { + transformer: { + babelTransformerPath: require.resolve( + "@lingui/metro-transformer/react-native" + ) + }, + resolver: { + sourceExts: [...sourceExts, "po", "pot"] + } +}; + +module.exports = mergeConfig(defaultConfig, config); +``` + + + + +## Usage + +:::tip +Take a look at the [example app](https://github.com/lingui/js-lingui/tree/main/examples/react-native) that uses the transformer. The transformer only supports catalogs based on `po` and `pot` files. + +The library is currently in beta. If you encounter any issues, please [report them](https://github.com/lingui/js-lingui/issues). +::: + +1. Import `.po` files directly in your code: + + ```diff + -import { messages } from "./src/locales/en/messages.ts"; + +import { messages } from "./src/locales/en/messages.po"; + ``` + +2. If you are using TypeScript, you need to add `.po` file declaration so that TypeScript understands the file extension: + + ```ts title="src/po-types.d.ts" + declare module "*.po" { + import type { Messages } from "@lingui/core"; + export const messages: Messages; + } + ``` + +3. Restart Metro bundler with `expo start -c` or `yarn start --reset-cache` to clear the transformer cache. +4. Profit! 🎉 + +:::danger +Whenever you make a change to the Lingui config file (this should not happen often), restart Metro bundler. +::: diff --git a/website/docs/tutorials/react-native.md b/website/docs/tutorials/react-native.md index 3160dc4fa..9ab230258 100644 --- a/website/docs/tutorials/react-native.md +++ b/website/docs/tutorials/react-native.md @@ -16,7 +16,7 @@ With the dependencies installed and set up, before running your app, please clea The React Native tutorial is similar to the one for [React](/docs/tutorials/react.md) and we highly recommend you read that one first because it goes into greater detail on many topics. Here, we will only cover parts that are relevant for React Native. :::tip Hint -If you're looking for a working solution, check out the [sources available here](https://github.com/lingui/js-lingui/tree/main/examples/react-native) and the [demo app on Expo](https://exp.host/@vonovak/js-lingui-demo). It showcases more functionality than this guide. +If you're looking for a working solution, check out the [sources available here](https://github.com/lingui/js-lingui/tree/main/examples/react-native). The example app showcases more functionality than this guide. ::: :::caution Note @@ -238,6 +238,7 @@ The important point here is that the sentence isn't broken into pieces but remai ## Further reading +- [Metro transformer for `po` files](/docs/ref/metro-transformer.mdx) - [Common i18n patterns in React](/docs/tutorials/react-patterns.md) - [`@lingui/react` reference documentation](/docs/ref/react.md) - [`@lingui/cli` reference documentation](/docs/ref/cli.md) diff --git a/website/sidebars.ts b/website/sidebars.ts index b8bc1a02c..b98a3e3c7 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -161,6 +161,11 @@ const sidebar = [ label: "@lingui/loader", id: "ref/loader", }, + { + type: "doc", + label: "@lingui/metro-transformer", + id: "ref/metro-transformer", + }, { type: "doc", label: "@lingui/extractor-vue",