Documentation

Окружающая среда

Intlayer с Next.js

Получение начальных знаний о интернационализации (i18n) с Intlayer и Next.js 15 App Router

Что такое Intlayer?

Intlayer — это инновационная, открытая библиотека интернационализации (i18n), разработанная для упрощения многозначной поддержки в современных веб-приложениях. Intlayer бесшовно интегрируется с последней версией Next.js 15, включая его мощный App Router. Он оптимизирован для работы с Серверными Компонентами для эффективной отрисовки и полностью совместим с Turbopack.

С помощью Intlayer вы можете:

Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
Динамически локализовать метаданные, маршруты и контент.
Получать доступ к переводам как в клиентских, так и в серверных компонентах.
Обеспечить поддержку TypeScript с помощью автогенерируемых типов, что улучшает автозаполнение и обнаружение ошибок.
Воспользоваться продвинутыми функциями, такими как динамическое определение локали и переключение.

Примечание: Intlayer совместим с Next.js 12, 13, 14 и 15. Если вы используете Next.js Page Router, вы можете обратиться к этому руководству. Для Next.js 12, 13, 14 с App Router обратитесь к этому руководству.

Пошаговое руководство по настройке Intlayer в приложении Next.js

Шаг 1: Установите зависимости

Установите необходимые пакеты с помощью npm:

bash

1npm install intlayer next-intlayer

bash

1yarn add intlayer next-intlayer

bash

1pnpm add intlayer next-intlayer

Шаг 2: Настройте проект

Создайте файл конфигурации для настройки языков вашего приложения:

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ENGLISH,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // Ваши другие локали
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export default config;

Чтобы увидеть все доступные параметры, обратитесь к документации по конфигурации здесь.

Шаг 3: Интегрируйте Intlayer в вашу конфигурацию Next.js

Настройте вашу сборку Next.js для использования Intlayer:

typescript

1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);

Шаг 4: Настройте Middleware для определения локали

Настройте middleware для обнаружения предпочтительной локали пользователя:

typescript

1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5  matcher: "/((?!api|static|.*\\..*|_next).*)",
6};

Шаг 5: Определите динамические маршруты локали

Реализуйте динамическую маршрутизацию для локализованного контента:

Смените src/app/page.ts на src/app/[locale]/page.ts

Затем реализуйте функцию generateStaticParams в вашей компоновке приложения.

tsx

1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // Строка для вставки
7
8const RootLayout = ({
9  children,
10}: Readonly<{
11  children: ReactNode;
12}>) => children;
13
14export default RootLayout;

Затем добавьте новую компоновку в вашей директории [locale]:

tsx

1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10  const { locale } = await params;
11  return (
12    <html lang={locale} dir={getHTMLTextDir(locale)}>
13      <body className={inter.className}>{children}</body>
14    </html>
15  );
16};
17
18export default LocaleLayout;

Шаг 6: Объявите ваш контент

Создайте и управляйте вашими словарями контента:

tsx

1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5  key: "page",
6  content: {
7    getStarted: {
8      main: t({
9        en: "Get started by editing",
10        fr: "Commencez par éditer",
11        es: "Comience por editar",
12      }),
13      pageLink: "src/app/page.tsx",
14    },
15  },
16} satisfies DeclarationContent;
17
18export default pageContent;

Посмотрите, как объявить ваши файлы деклараций Intlayer.

Шаг 7: Используйте контент в вашем коде

Получите доступ к вашим словарям контента по всему вашему приложению:

tsx

1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11  const { title, content } = useIntlayer("page");
12
13  return (
14    <>
15      <p>{content.getStarted.main}</p>
16      <code>{content.getStarted.pageLink}</code>
17    </>
18  );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22  const { locale } = await params;
23
24  return (
25    <>
26      {/**
27       *   IntlayerServerProvider используется для предоставления локали серверным дочерним элементам
28       *   Не работает, если установлено в компоновке
29       */}
30      <IntlayerServerProvider locale={locale}>
31        <PageContent />
32        <ServerComponentExample />
33      </IntlayerServerProvider>
34      {/**
35       *   IntlayerClientProvider используется для предоставления локали клиентским дочерним элементам
36       *   Может быть установлен в любом родительском компоненте, включая компоновку
37       */}
38      <IntlayerClientProvider locale={locale}>
39        <ClientComponentExample />
40      </IntlayerClientProvider>
41    </>
42  );
43};
44
45export default Page;

tsx

1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8  const content = useIntlayer("client-component-example"); // Создайте соответствующее объявление контента
9
10  return (
11    <div>
12      <h2>{content.title} </h2>
13      <p>{content.content}</p>
14    </div>
15  );
16};

tsx

1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6  const content = useIntlayer("server-component-example"); // Создайте соответствующее объявление контента
7
8  return (
9    <div>
10      <h2>{content.title} </h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

Примечание: Если вы хотите использовать свой контент в атрибутах string, таких как alt, title, href, aria-label и т.д., вы должны вызвать значение функции, например:
tsx
1<img src={content.image.src.value} alt={content.image.value} />

Для более подробного использования intlayer в клиентских или серверных компонентах смотрите пример Next.js здесь.

(Дополнительно) Шаг 8: Интернационализация ваших метаданных

В случае если вы хотите интернационализировать ваши метаданные, такие как заголовок вашей страницы, вы можете использовать функцию generateMetadata, предоставленную Next.js. Внутри функции используйте функцию getTranslationContent, чтобы перевести ваши метаданные.

typescript

1// src/app/[locale]/layout.tsx или src/app/[locale]/page.tsx
2
3import {
4  type IConfigLocales,
5  getTranslationContent,
6  getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12  params: { locale },
13}: LocalParams): Metadata => {
14  const t = <T>(content: IConfigLocales<T>) =>
15    getTranslationContent(content, locale);
16
17  /**
18   * Генерирует объект, содержащий все URL для каждой локали.
19   *
20   * Пример:
21   * ```ts
22   *  getMultilingualUrls('/about');
23   *
24   *  // Возвращает
25   *  // {
26   *  //   en: '/about',
27   *  //   fr: '/fr/about',
28   *  //   es: '/es/about',
29   *  // }
30   * ```
31   */
32  const multilingualUrls = getMultilingualUrls("/");
33
34  return {
35    title: t<string>({
36      en: "My title",
37      fr: "Mon titre",
38      es: "Mi título",
39    }),
40    description: t({
41      en: "My description",
42      fr: "Ma description",
43      es: "Mi descripción",
44    }),
45    alternates: {
46      canonical: url,
47      languages: { ...multilingualUrls, "x-default": "/" },
48    },
49    openGraph: {
50      url: multilingualUrls[locale],
51    },
52  };
53};
54
55// ... Остальная часть кода

Узнайте больше о оптимизации метаданных в официальной документации Next.js.

(Дополнительно) Шаг 9: Интернационализация вашего sitemap.xml и robots.txt

Для интернационализации вашего sitemap.xml и robots.txt, вы можете использовать функцию getMultilingualUrls, предоставленную Intlayer. Эта функция позволяет вам генерировать многоязычные URL для вашего sitemap.

tsx

1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7  {
8    url: "https://example.com",
9    alternates: {
10      languages: getMultilingualUrls("https://example.com"),
11    },
12  },
13  {
14    url: "https://example.com/login",
15    alternates: {
16      languages: getMultilingualUrls("https://example.com/login"),
17    },
18  },
19  {
20    url: "https://example.com/register",
21    alternates: {
22      languages: getMultilingualUrls("https://example.com/register"),
23    },
24  },
25];
26
27export default sitemap;

tsx

1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9  rules: {
10    userAgent: "*",
11    allow: ["/"],
12    disallow: getAllMultilingualUrls(["/login", "/register"]),
13  },
14  host: "https://example.com",
15  sitemap: `https://example.com/sitemap.xml`,
16});
17
18export default robots;

Узнайте больше об оптимизации sitemap в официальной документации Next.js. Узнайте больше об оптимизации robots.txt в официальной документации Next.js.

(Дополнительно) Шаг 10: Изменение языка вашего контента

Чтобы изменить язык вашего контента, вы можете использовать функцию setLocale, предоставленную хуком useLocale. Эта функция позволяет вам установить локаль приложения и обновить контент соответственно.

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.English)}>Изменить язык</button>
9  );
10};

Настройка TypeScript

Intlayer использует модульную расширяемость, чтобы получить преимущества TypeScript и сделать ваш код более надежным.

alt text

Убедитесь, что ваша конфигурация TypeScript включает автогенерируемые типы.

json5

1// tsconfig.json
2
3{
4  // ваша настраиваемая конфигурация
5  include: [
6    "src",
7    "types", // <- Включите авто сгенерированные типы
8  ],
9}

Конфигурация Git

Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит вам избежать их коммита в ваш Git репозиторий.

Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:

gitignore

1# Игнорировать файлы, сгенерированные Intlayer
2.intlayer

Если у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.

Ссылка на документацию GitHub

Получение функции Next.js 14 и App Router

Получение начальных знаний о интернационализации (i18n) с Intlayer и Next.js 15 App Router

Что такое Intlayer?

Пошаговое руководство по настройке Intlayer в приложении Next.js

Шаг 1: Установите зависимости

Шаг 2: Настройте проект

Шаг 3: Интегрируйте Intlayer в вашу конфигурацию Next.js

Шаг 4: Настройте Middleware для определения локали

Шаг 5: Определите динамические маршруты локали

Шаг 6: Объявите ваш контент

Шаг 7: Используйте контент в вашем коде

(Дополнительно) Шаг 8: Интернационализация ваших метаданных

(Дополнительно) Шаг 9: Интернационализация вашего sitemap.xml и robots.txt

(Дополнительно) Шаг 10: Изменение языка вашего контента

Настройка TypeScript

Конфигурация Git

На этой странице