astro-react-i18next v0.3.1
astro-react-i18next
Integrates i18next and react-i18next seamlessly into your Astro website to provide robust i18n support for React components.
Examples
| Example | |
|---|---|
| SSG |  |
| SSR | |
Installation
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(),
],
});Configuration
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",
+ }),
});Locale Resources
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.jsonThe content of the locales/en-US/common.json file should look like this:
{
"hello_world": "Hello, World!"
}Dynamic Routes for Locales
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.jsonStatic Paths for Locales
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>Translating Content in Astro Components
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>Translating Content in React Components
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>;
}Utilities
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. |
Developing locally
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)License
Licensed under the MIT License.