docs: add metro-transformer docs

Author: vonovak

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` command, so that you can `import` `.po` files directly, instead of running `lingui compile` and `import`ing its output.
 
 ## Installation
 

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 provides a transformer for Metro to compile `.po` message catalogs on the fly. It's an alternative to the `lingui compile`, so that you can `import` `.po` files directly, instead of running `lingui compile` and `import`ing its output.
+
+## Installation
+
+:::note
+Only Expo SDK 49 and React Native v0.72.1 or newer are supported.
+
+The library is currently in beta. If you encounter any issues, please [report them](https://github.com/lingui/js-lingui/issues).
+:::
+
+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):
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+<Tabs groupId="babel-swc">
+  <TabItem value="expo" label="Expo" default>
+
+```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,
+  assetExts: resolver.assetExts.filter((ext) => ext !== "po"),
+  sourceExts: [...resolver.sourceExts, "po"],
+};
+
+module.exports = config;
+```
+
+  </TabItem>
+<TabItem value="plain-RN" label="plain React Native">
+
+```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: {
+    assetExts: assetExts.filter((ext) => ext !== "po"),
+    sourceExts: [...sourceExts, "po"]
+  }
+};
+
+module.exports = mergeConfig(defaultConfig, config);
+```
+
+</TabItem>
+</Tabs>
+
+## Usage
+
+:::tip
+Take a look at the [example app](https://github.com/lingui/js-lingui/tree/main/examples/react-native) that uses the transformer. Only `.po` files are supported by the transformer.
+:::
+
+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! 🎉

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",