Integrates i18next and react-i18next seamlessly into your Astro website to provide robust i18n support for React components.
| Example | |
|---|---|
| SSG |  |
| SSR | |
npx astro add astro-react-i18nextFollow the prompts to install the necessary dependencies and add the required configuration to your Astro project.
You will see the following changes in your astro.config.mjs file:
import { defineConfig } from "astro/config";
import reactI18next from "astro-react-i18next";
export default defineConfig({
// ...
integrations: [
// ...
+ reactI18next(),
],
});The initialization function accepts an optional configuration object with the following options:
| Option | Type | Description | Default |
|---|---|---|---|
defaultLocale |
string |
The default locale to use when no locale is specified. | "en-US" |
locales |
string[] |
An array of locales to support. | ["en-US"] |
defaultNamespace |
string |
The default namespace to use when no namespace is specified. | "common" |
namespaces |
string[] |
An array of namespaces to support. | ["common"] |
prefixDefaultLocale |
boolean |
Whether to prefix the default locale with the locale code. | false |
localesDir |
string |
The directory where the locale files are stored, relative to the public directory. | "locales" |
domains |
{ domain: string; defaultLocale: string; }[] |
An array of domains for language selection. | [] |
reservedRoutes |
string[] |
An array of routes excluded from locale handling. | ["/api"] |
Here is an example of how to configure the integration:
import { defineConfig } from "astro/config";
import reactI18next from "astro-react-i18next";
export default defineConfig({
// ...
integrations: [
// ...
- reactI18next(),
+ reactI18next({
+ defaultLocale: "en-US",
+ locales: ["en-US", "fr-FR", "zh-TW"],
+ }),
],
});It also supports Server (SSR) Mode, such as using the @astrojs/node adapter:
import { defineConfig } from "astro/config";
+import node from '@astrojs/node';
import reactI18next from "astro-react-i18next";
export default defineConfig({
// ...
integrations: [
// ...
reactI18next({
defaultLocale: "en-US",
locales: ["en-US", "fr-FR", "zh-TW"],
}),
],
+ output: "server",
+ adapter: node({
+ mode: "standalone",
+ }),
});Create locale files for each locale and namespace in the localesDir directory.
For example, create the following files:
/
├── public/
│ └── locales/
│ ├── en-US/
│ │ └── common.json
│ ├── fr-FR/
│ │ └── common.json
│ └── zh-TW/
│ └── common.json
├── src/
└── package.json
The content of the locales/en-US/common.json file should look like this:
{
"hello_world": "Hello, World!"
}To manage dynamic routes for each locale, create a root route named [...locale] in the pages directory.
/
├── public/
├── src/
│ └── pages/
│ └── [...locale]/
│ ├── index.astro
│ ├── page-a.astro
│ └── page-b.astro
└── package.json
If you're using Static (SSG) Mode, static paths are required. You can easily generate them by using the buildStaticPaths utility function provided by this integration.
---
import { buildStaticPaths } from "astro-react-i18next/utils";
export function getStaticPaths() {
return buildStaticPaths();
}
---
<html>
...
</html>Use the i18next instance to translate content in your Astro components.
---
import i18n from "i18next";
---
<html lang={i18n.language}>
<p>{i18n.t("hello_world")}</p>
</html>Use the useTranslation hook to translate content in your React components.
import { useTranslation } from "react-i18next";
export function MyComponent() {
const { t } = useTranslation();
return <p>{t("hello_world")}</p>;
}The integration provides utility functions to help manage locales and translations.
All utility functions are available in the astro-react-i18next/utils module.
| Function | Description | Returns |
|---|---|---|
getLocaleConfig() |
Returns the locale configuration object. | { defaultLocale: string; locales: string[]; prefixDefaultLocale: boolean; domains: { domain: string; defaultLocale: string; }[]; reservedRoutes: string[]; } |
getLocalizedPathname(pathname = "", locale = "") |
Returns the localized pathname for the specified locale. | string |
buildStaticPaths() |
Generates static paths for each locale. | { params: { locale: string | undefined; }; }[] |
changeLocale(nextLocale = "", shallow = true) |
Changes the current locale. |
Clone the repository:
git clone https://github.com/jeremyxgo/astro-react-i18next.git
cd astro-react-i18nextBuild the package:
npm run buildInstall the package in your project:
npm install $(npm pack /path/to/astro-react-i18next | tail -1)Licensed under the MIT License.
