diff --git a/website/docs/ref/vite-plugin.md b/website/docs/ref/vite-plugin.md index 7634da549..48a132244 100644 --- a/website/docs/ref/vite-plugin.md +++ b/website/docs/ref/vite-plugin.md @@ -1,8 +1,10 @@ # Vite Plugin -It's a good practice to use compiled message catalogs during development. However, running [`compile`](/docs/ref/cli.md#compile) everytime messages are changed soon becomes tedious. +`@lingui/vite-plugin` is a Vite plugin, which compiles `.po` catalogs on the fly and provides additional required configuration for Vite. -`@lingui/vite-plugin` is a Vite plugin, which compiles `.po` catalogs on the fly: +:::note +Refer to [Setup with Vite](/docs/tutorials/setup-vite.md) for a full installation guide. +::: ## Installation diff --git a/website/docs/tutorials/setup-react.md b/website/docs/tutorials/setup-react.md index 3412b2737..25cd58b68 100644 --- a/website/docs/tutorials/setup-react.md +++ b/website/docs/tutorials/setup-react.md @@ -8,7 +8,7 @@ This setup guide is for any project which uses React. ## Install -1. Install `@lingui/cli`, `@lingui/macro`, *babel-plugin-macros* and Babel [^1] core packages as a development dependencies and `@lingui/react` as a runtime dependency. +1. Install `@lingui/cli`, `@lingui/macro`, `babel-plugin-macros` and Babel [^1] core packages as a development dependencies and `@lingui/react` as a runtime dependency. ```bash npm2yarn npm install --save-dev @lingui/cli @babel/core diff --git a/website/docs/tutorials/setup-vite.md b/website/docs/tutorials/setup-vite.md new file mode 100644 index 000000000..b131b9693 --- /dev/null +++ b/website/docs/tutorials/setup-vite.md @@ -0,0 +1,147 @@ +# Setup with Vite + +The Lingui Vite integration: +- Supports both [@vitejs/plugin-react](https://www.npmjs.com/package/@vitejs/plugin-react) and [@vitejs/plugin-react-swc](https://www.npmjs.com/package/@vitejs/plugin-react-swc) +- Compiles `.po` catalogs on the fly + +## Setup with [@vitejs/plugin-react](https://www.npmjs.com/package/@vitejs/plugin-react) {#setup-with-vitejs-plugin-react} + +`@vitejs/plugin-react` uses Babel to transform your code. LinguiJS rely on `babel-plugin-macros` to compile JSX to [ICU Message Format](/docs/ref/message-format.md) and for automatic ID generation. + +1. Install `@lingui/cli`, `babel-plugin-macros` as development dependencies and `@lingui/macro`, `@lingui/react` as a runtime dependency: + + ```bash npm2yarn + npm install --save-dev @lingui/cli babel-plugin-macros + npm install --save @lingui/react @lingui/macro + ``` + +2. Setup Lingui in `vite.config.ts`: + + :::info + `@vitejs/plugin-react` does not use babel config (e.g. `babel.rc`) from your project by default. You have to enable it manually or specify babel options directly in `vite.config.ts` + ::: + + ```ts title="vite.config.ts" + import { defineConfig } from "vite"; + import react from "@vitejs/plugin-react"; + import lingui from "@lingui/vite-plugin"; + + export default defineConfig({ + plugins: [ + react({ + babel: { + plugins: ["macros"] + } + }), + lingui() + ] + }); + ``` + +## Setup with [@vitejs/plugin-react-swc](https://www.npmjs.com/package/@vitejs/plugin-react-swc) {#setup-with-vitejs-plugin-react-swc} + +`@vitejs/plugin-react-swc` uses [SWC](https://swc.rs/) to transform your code, which is 20x faster than Babel. LinguiJS rely on [`@lingui/swc-plugin`](/docs/ref/swc-plugin.md) to compile JSX to [ICU Message Format](/docs/ref/message-format.md) and for automatic ID generation. + +1. Install `@lingui/cli`, `@lingui/swc-plugin` as development dependencies and `@lingui/macro`, `@lingui/react` as a runtime dependency: + + ```bash npm2yarn + npm install --save-dev @lingui/cli @lingui/swc-plugin + npm install --save @lingui/react @lingui/macro + ``` + +2. Setup Lingui in `vite.config.ts`: + + ```ts title="vite.config.ts" + import { defineConfig } from "vite"; + import react from "@vitejs/plugin-react-swc"; + import lingui from "@lingui/vite-plugin"; + + export default defineConfig({ + plugins: [ + react({ + plugins: [["@lingui/swc-plugin", {}]] + }), + lingui(), + ] + }); + ``` +## Further Setup + +1. Create a `lingui.config.js` file with LinguiJS configuration in the root of your project (next to `package.json`). Replace `src` with a directory name where you have source files: + + ```js title="lingui.config.js" + /** @type {import('@lingui/conf').LinguiConfig} */ + module.exports = { + locales: ["en", "cs", "fr"], + catalogs: [{ + path: "src/locales/{locale}", + include: ["src"] + }], + format: "po" + } + ``` + + PO format is recommended for message catalogs, and could be compiled on the fly thanks to `@lingui/vite-plugin`. + + See [`format`](/docs/ref/catalog-formats.md) documentation for other available formats. + +2. Add the following scripts to your `package.json`: + + ```json title="package.json" + { + "scripts": { + "messages:extract": "lingui extract" + } + } + ``` + +3. Check the installation by running: + + ```bash npm2yarn + npm run messages:extract + ``` + + There should be no error and you should see output similar following: + + ```bash npm2yarn + > npm run messages:extract + + Catalog statistics: + ┌──────────┬─────────────┬─────────┐ + │ Language │ Total count │ Missing │ + ├──────────┼─────────────┼─────────┤ + │ cs │ 0 │ 0 │ + │ en │ 0 │ 0 │ + │ fr │ 0 │ 0 │ + └──────────┴─────────────┴─────────┘ + + (use "lingui extract" to update catalogs with new messages) + (use "lingui compile" to compile catalogs for production) + ``` + + This command should create `.po` catalogs in the `src/locales/` folder: + + ```bash + src + └── locales + ├── cs.po + ├── en.po + └── fr.po + ``` + +4. Import `.po` those files directly in your Vite processed code: + + ```ts + export async function dynamicActivate(locale: string) { + const { messages } = await import(`./locales/${locale}.po`); + + i18n.load(locale, messages) + i18n.activate(locale) + } + ``` + +See the [guide about dynamic loading catalogs](/docs/guides/dynamic-loading-catalogs.md) for more info. + +See [Vite's official documentation](https://vitejs.dev/guide/features.html#dynamic-import) for more info about Vite dynamic imports. + +Congratulations! You've successfully set up a Vite project with LinguiJS. Now it's a good time to follow [React tutorial](/docs/tutorials/react.md) or read about [ICU Message Format](/docs/ref/message-format.md) which is used in messages. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 4b9b30d7b..fad192bdc 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -15,6 +15,14 @@ module.exports = { disableSwitch: false, respectPrefersColorScheme: true, }, + announcementBar: { + id: 'new_release', + content: + 'The v4.0.0 Pre-Release is here, discover its new capabilities!', + backgroundColor: '#ef4242', + textColor: '#FFFFFF', + isCloseable: true, + }, navbar: { title: '', logo: { diff --git a/website/sidebars.ts b/website/sidebars.ts index ddac9fb1b..396654294 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -18,6 +18,11 @@ const sidebar = [ label: 'React project', id: 'tutorials/setup-react', }, + { + type: 'doc', + label: 'Vite project', + id: 'tutorials/setup-vite', + }, ], }, {