Перевод вашего сайта на Next.js 16 с помощью Intlayer | Интернационализация (i18n)

ВидеоКодДемо

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-next-16-template.vercel.app

Open embedded page in fullscreen

Смотрите Шаблон приложения на GitHub.

Содержание

Почему Intlayer лучше альтернатив?

По сравнению с основными решениями, такими как next-intl или i18next, Intlayer представляет собой решение со встроенными оптимизациями, такими как:

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

1. 1

   Установка зависимостей

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer next-intlayer
   

   • intlayer

     Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.

   • next-intlayer

     Пакет, который интегрирует Intlayer с Next.js. Он предоставляет провайдеры контекста и хуки для интернационализации в Next.js. Кроме того, включает плагин Next.js для интеграции Intlayer с Webpack или Turbopack, а также прокси для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.

2. 2

   Настройте ваш проект

   Вот окончательная структура, которую мы создадим:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   .
   ├── src
   │   ├── app
   │   │   ├── [locale]
   │   │   │   ├── layout.tsx            # Локальный макет для провайдера Intlayer
   │   │   │   ├── page.content.ts
   │   │   │   └── page.tsx
   │   │   └── layout.tsx                # Корневой макет для стилей и глобальных провайдеров
   │   ├── components
   │   │   ├── client-component-example.content.ts
   │   │   ├── ClientComponentExample.tsx
   │   │   ├── LocaleSwitcher
   │   │   │   ├── localeSwitcher.content.ts
   │   │   │   └── LocaleSwitcher.tsx
   │   │   ├── server-component-example.content.ts
   │   │   └── ServerComponentExample.tsx
   │   └── proxy.ts
   ├── intlayer.config.ts
   ├── next.config.ts
   ├── package.json
   └── tsconfig.json
   

   Если вы не хотите использовать локальный роутинг, intlayer можно использовать как простой провайдер / хук. Смотрите это руководство для получения подробной информации.

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

   intlayer.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Ваши другие локали
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   С помощью этого файла конфигурации вы можете настроить локализованные URL, прокси-перенаправление, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

3. 3

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

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

   next.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { NextConfig } from "next";
   import { withIntlayer } from "next-intlayer/server";
   
   const nextConfig: NextConfig = {/* параметры конфигурации здесь */};
   
   export default withIntlayer(nextConfig);
   

   Плагин Next.js withIntlayer() используется для интеграции Intlayer с Next.js. Он обеспечивает сборку файлов деклараций контента и их мониторинг в режиме разработки. Он определяет переменные окружения Intlayer в средах Webpack или Turbopack. Кроме того, он предоставляет алиасы для оптимизации производительности и обеспечивает совместимость с серверными компонентами.

   Функция withIntlayer() является асинхронной функцией. Она позволяет подготовить словари Intlayer перед началом сборки. Если вы хотите использовать её с другими плагинами, вы можете использовать await. Пример:

   ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   const nextConfig = await withIntlayer(nextConfig);
   const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
   
   export default nextConfigWithOtherPlugins;
   

   Если вы хотите использовать его синхронно, вы можете использовать функцию withIntlayerSync(). Пример:

   ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   const nextConfig = withIntlayerSync(nextConfig);
   const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
   
   export default nextConfigWithOtherPlugins;
   

   Intlayer автоматически определяет, использует ли ваш проект webpack или Turbopack, на основе флагов командной строки --webpack, --turbo или --turbopack, а также вашей текущей версии Next.js.

   Начиная с next>=16, если вы используете Rspack, вы должны явно заставить Intlayer использовать конфигурацию webpack, отключив Turbopack:

   ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
   

4. 4

   Определите динамические маршруты локалей

   Удалите всё из RootLayout и замените следующим кодом:

   src/app/layout.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { PropsWithChildren, FC } from "react";
   import "./globals.css";
   
   const RootLayout: FC<PropsWithChildren> = ({ children }) => (
     // Вы всё ещё можете обернуть children в другие провайдеры, такие как `next-themes`, `react-query`, `framer-motion` и т.д.
     <>{children}</>
   );
   
   export default RootLayout;
   

   Оставляя компонент RootLayout пустым, вы позволяете установить атрибуты lang и dir для тега <html>.

   Для реализации динамической маршрутизации укажите путь для локали, добавив новый макет в ваш каталог [locale]:

   Intlayer >=9.4Intlayer <9.4

   src/app/[locale]/layout.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { type NextLayoutIntlayer } from "next-intlayer";
   import { IntlayerProvider } from "next-intlayer/server";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
     const { locale } = await params;
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <body className={inter.className}>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
         </body>
       </html>
     );
   };
   
   export default LocaleLayout;
   

   Один IntlayerProvider охватывает обе части дерева: он инициализирует контекст сервера, привязанный к запросу, который читается серверными хуками, и монтирует клиентского провайдера, чтобы клиентские компоненты получали одну и ту же локаль.

   src/app/[locale]/layout.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
     const { locale } = await params;
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <body className={inter.className}>
           <IntlayerClientProvider locale={locale}>
             {children}
           </IntlayerClientProvider>
         </body>
       </html>
     );
   };
   
   export default LocaleLayout;
   

   Сегмент пути [locale] используется для определения локали. Пример: /en-US/about будет соответствовать en-US, а /fr/about, fr.

   На этом этапе вы столкнетесь с ошибкой: Error: Missing <html> and <body> tags in the root layout.. Это ожидаемо, так как файл /app/page.tsx больше не используется и может быть удален. Вместо этого сегмент пути [locale] активирует страницу /app/[locale]/page.tsx. Следовательно, страницы будут доступны по путям, таким как /en, /fr, /es в вашем браузере. Чтобы установить локаль по умолчанию как корневую страницу, обратитесь к настройке proxy в шаге 7.

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

   src/app/[locale]/layout.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   export { generateStaticParams } from "next-intlayer"; // Строка для вставки
   
   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
     /*... Остальная часть кода*/
   };
   
   export default LocaleLayout;
   

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

   Intlayer работает с export const dynamic = 'force-static';, чтобы обеспечить предварительную сборку страниц для всех локалей.

5. 5

   Объявите ваш контент

   Создайте и управляйте объявлениями контента для хранения переводов:

   src/app/[locale]/page.content.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       getStarted: {
         main: t({
           en: "Get started by editing",
           fr: "Commencez par éditer",
           es: "Comience por editar",
         }),
         pageLink: "src/app/page.tsx",
       },
     },
   } satisfies Dictionary;
   
   export default pageContent;
   

   Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они включены в каталог contentDir (по умолчанию, ./src). И соответствуют расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Для получения дополнительной информации обратитесь к документации по объявлениям контента.

6. 6

   Использование контента в вашем коде

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

   Intlayer >=9.4Intlayer <9.4

   src/app/[locale]/page.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { FC } from "react";
   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type NextPageIntlayer, useIntlayer } from "next-intlayer";
   
   const PageContent: FC = () => {
     const content = useIntlayer("page");
   
     return (
       <>
         <p>{content.getStarted.main}</p>
         <code>{content.getStarted.pageLink}</code>
       </>
     );
   };
   
   const Page: NextPageIntlayer = () => (
     <>
       <PageContent />
       <ServerComponentExample />
   
       <ClientComponentExample />
     </>
   );
   
   export default Page;
   

   • IntlayerProvider монтируется один раз в локальном layout. Он предоставляет локаль как серверным, так и клиентским компонентам, поэтому страницы больше не оборачиваются сами в себя.
   • Серверные hooks разрешают локаль в следующем порядке: локаль, передаваемая на месте вызова, затем контекст сервера, инициализированный provider'ом, затем локаль, содержащаяся в запросе (заголовок x-intlayer-locale, установленный прокси-сервером Intlayer, затем cookie локали). Этот последний шаг — это то, что сохраняет контент в актуальном состоянии при навигации на стороне клиента, которая перестраивает только сегмент страницы, где layout — и вместе с ним provider — не перезапускается.

   src/app/[locale]/page.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { FC } from "react";
   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type NextPageIntlayer } from "next-intlayer";
   import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
   
   const PageContent: FC = () => {
     const content = useIntlayer("page");
   
     return (
       <>
         <p>{content.getStarted.main}</p>
         <code>{content.getStarted.pageLink}</code>
       </>
     );
   };
   
   const Page: NextPageIntlayer = async ({ params }) => {
     const { locale } = await params;
   
     return (
       <IntlayerServerProvider locale={locale}>
         <PageContent />
         <ServerComponentExample />
   
         <ClientComponentExample />
       </IntlayerServerProvider>
     );
   };
   
   export default Page;
   

   • IntlayerClientProvider используется для предоставления локали компонентам на стороне клиента. Его можно разместить в любом родительском компоненте, включая макет. Однако рекомендуется размещать его в макете, так как Next.js разделяет код макета между страницами, что делает это более эффективным. Используя IntlayerClientProvider в макете, вы избегаете повторной инициализации для каждой страницы, улучшая производительность и поддерживая единый контекст локализации во всем приложении.

   • IntlayerServerProvider используется для предоставления локали дочерним компонентам на сервере. Его нельзя устанавливать в макете.

     Макет и страница не могут использовать общий серверный контекст, поскольку система серверного контекста основана на хранилище данных для каждого запроса (через механизм React's cache), из-за чего каждый "контекст" создаётся заново для разных сегментов приложения. Размещение провайдера в общем макете нарушит эту изоляцию, препятствуя правильной передаче значений серверного контекста вашим серверным компонентам.

   src/components/ClientComponentExample.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   "use client";
   
   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   export const ClientComponentExample: FC = () => {
     const content = useIntlayer("client-component-example"); // Создайте декларацию связанного контента
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   Intlayer >=9.4Intlayer <9.4

   src/components/ServerComponentExample.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   export const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // Создать связанное объявление контента
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   next-intlayer — это изоморфный путь импорта: условие экспорта react-server предоставляет серверным компонентам реализацию с окружающей локалью, в то время как клиентские компоненты получают реализацию на основе контекста. Один и тот же вызов работает с обеих сторон.

   src/components/ServerComponentExample.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer/server";
   
   export const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // Создание связанного объявления контента
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   Если вы хотите использовать ваш контент в атрибуте типа string, таком как alt, title, href, aria-label и т.д., вы должны вызвать значение функции, например:

   html

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <img src="{content.image.src.value}" alt="{content.image.value}" />
   <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
   <img src="{String(content.image.src)}" alt="{String(content.image)}" />
   

   Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.

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

7. 7

   Настройка прокси для определения локали

   Необязательно

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

   src/proxy.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   export { intlayerProxy as proxy } from "next-intlayer/proxy";
   
   export const config = {
     matcher:
       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
   };
   

   intlayerProxy используется для определения предпочтительной локали пользователя и перенаправления его на соответствующий URL, как указано в конфигурации. Кроме того, он позволяет сохранять предпочтительную локаль пользователя в cookie.

   С версии Intlayer v9 это middleware соответствует параметру routing.enableProxy (true по умолчанию). Установите routing.enableProxy: false в вашей конфигурации, чтобы превратить его в pass-through без удаления этого файла. См. примечания к выпуску v9.

   Если необходимо объединить несколько прокси вместе (например, intlayerProxy с аутентификацией или кастомными прокси), Intlayer теперь предоставляет помощник под названием multipleProxies.

   ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";
   import { customProxy } from "@utils/customProxy";
   
   export const proxy = multipleProxies([intlayerProxy, customProxy]);
   

8. 8

   Интернационализация ваших метаданных

   Необязательно

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

   src/app/[locale]/metadata.content.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { type Dictionary, t } from "intlayer";
   import { Metadata } from "next";
   
   const metadataContent = {
     key: "page-metadata",
     content: {
       title: t({
         en: "Create Next App",
         fr: "Créer une application Next.js",
         es: "Crear una aplicación Next.js",
       }),
       description: t({
         en: "Generated by create next app",
         fr: "Généré par create next app",
         es: "Generado por create next app",
       }),
     },
   } satisfies Dictionary<Metadata>;
   
   export default metadataContent;
   

   src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { getIntlayer, getMultilingualUrls } from "intlayer";
   import type { Metadata } from "next";
   import type { LocalPromiseParams } from "next-intlayer";
   
   export const generateMetadata = async ({
     params,
   }: LocalPromiseParams): Promise<Metadata> => {
     const { locale } = await params;
   
     const metadata = getIntlayer("page-metadata", locale);
   
     /**
      * Генерирует объект, содержащий все URL для каждой локали.
      *
      * Пример:
      * ```ts
      *  getMultilingualUrls('/about');
      *
      *  // Возвращает
      *  // {
      *  //   en: '/about',
      *  //   fr: '/fr/about',
      *  //   es: '/es/about',
      *  // }
      * ```
      */
     const multilingualUrls = getMultilingualUrls("/");
     const localizedUrl =
       multilingualUrls[locale as keyof typeof multilingualUrls];
   
     return {
       ...metadata,
       alternates: {
         canonical: localizedUrl,
         languages: { ...multilingualUrls, "x-default": "/" },
       },
       openGraph: {
         url: localizedUrl,
       },
     };
   };
   
   // ... Остальная часть кода
   

   Обратите внимание, что функция getIntlayer, импортируемая из next-intlayer, возвращает ваш контент, обёрнутый в IntlayerNode, что позволяет интегрироваться с визуальным редактором. В то время как функция getIntlayer, импортируемая из intlayer, возвращает ваш контент напрямую без дополнительных свойств.

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

9. 9

   Интернационализация ваших sitemap.xml и robots.txt

   Необязательно

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

   src/app/sitemap.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { getMultilingualUrls } from "intlayer";
   import type { MetadataRoute } from "next";
   
   const sitemap = (): MetadataRoute.Sitemap => [
     {
       url: "https://example.com",
       alternates: {
         languages: {
           ...getMultilingualUrls("https://example.com"),
           "x-default": "https://example.com",
         },
       },
     },
     {
       url: "https://example.com/login",
       alternates: {
         languages: {
           ...getMultilingualUrls("https://example.com/login"),
           "x-default": "https://example.com/login",
         },
       },
     },
     {
       url: "https://example.com/register",
       alternates: {
         languages: {
           ...getMultilingualUrls("https://example.com/register"),
           "x-default": "https://example.com/register",
         },
       },
     },
   ];
   
   export default sitemap;
   

   src/app/robots.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { MetadataRoute } from "next";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const robots = (): MetadataRoute.Robots => ({
     rules: {
       userAgent: "*",
       allow: ["/"],
       disallow: getAllMultilingualUrls(["/login", "/register"]),
     },
     host: "https://example.com",
     sitemap: `https://example.com/sitemap.xml`,
   });
   
   export default robots;
   

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

10. 10

    Изменение языка вашего контента

    Необязательно

    Чтобы изменить язык вашего контента в Next.js, рекомендуется использовать компонент Link для перенаправления пользователей на соответствующую локализованную страницу. Компонент Link позволяет предварительно загружать страницу, что помогает избежать полной перезагрузки страницы.

    src/components/LocaleSwitcher.tsx

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    "use client";
    
    import type { FC } from "react";
    import {
      Locales,
      getHTMLTextDir,
      getLocaleName,
      getLocalizedUrl,
    } from "intlayer";
    import { useLocale } from "next-intlayer";
    import Link from "next/link";
    
    export const LocaleSwitcher: FC = () => {
      const { locale, pathWithoutLocale, availableLocales, setLocale } =
        useLocale();
    
      return (
        <div>
          <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
          <div id="localePopover" popover="auto">
            {availableLocales.map((localeItem) => (
              <Link
                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
                key={localeItem}
                aria-current={locale === localeItem ? "page" : undefined}
                onClick={() => setLocale(localeItem)}
                replace // Будет гарантировать, что кнопка "назад" в браузере перенаправит на предыдущую страницу
              >
                <span>
                  {/* Локаль - например, FR */}
                  {localeItem}
                </span>
                <span>
                  {/* Язык на его собственной локали - например, Français */}
                  {getLocaleName(localeItem, locale)}
                </span>
                <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                  {/* Язык на текущей локали - например, Francés при установленной локали Locales.SPANISH */}
                  {getLocaleName(localeItem)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Язык на английском - например, French */}
                  {getLocaleName(localeItem, Locales.ENGLISH)}
                </span>
              </Link>
            ))}
          </div>
        </div>
      );
    };
    

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

    Вы также можете установить функцию в опции onLocaleChange, чтобы вызвать пользовательскую функцию при изменении локали.

    src/components/LocaleSwitcher.tsx

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    "use client";
    
    import { useLocale } from "next-intlayer";
    import { getLocalizedUrl } from "intlayer";
    
    // ... Остальная часть кода
    
    const { setLocale } = useLocale();
    
    return (
      <button onClick={() => setLocale(Locales.FRENCH)}>
        Переключить на французский
      </button>
    );
    

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

    • хук useLocale
    • хук getLocaleName
    • хук getLocalizedUrl
    • хук getHTMLTextDir
    • атрибут hrefLang
    • атрибут lang
    • атрибут dir
    • атрибут aria-current

11. 11

    Создание локализованного компонента Link

    Необязательно

    Чтобы навигация вашего приложения соответствовала текущей локали, вы можете создать кастомный компонент Link. Этот компонент автоматически добавляет префикс текущего языка к внутренним URL-адресам. Например, когда франкоязычный пользователь нажимает на ссылку "О нас", он перенаправляется на /fr/about вместо /about.

    Это поведение полезно по нескольким причинам:

    • SEO и пользовательский опыт: Локализованные URL-адреса помогают поисковым системам правильно индексировать страницы на определенных языках и предоставляют пользователям контент на их предпочтительном языке.
    • Согласованность: Используя локализованную ссылку во всем приложении, вы гарантируете, что навигация остается в пределах текущей локали, предотвращая неожиданные переключения языков.
    • Поддержка: Централизация логики локализации в одном компоненте упрощает управление URL-адресами, делая ваш код более простым в поддержке и расширении по мере роста вашего приложения.

    Ниже приведена реализация локализованного компонента Link на TypeScript:

    src/components/Link.tsx

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    "use client";
    
    import { getLocalizedUrl } from "intlayer";
    import NextLink, { type LinkProps as NextLinkProps } from "next/link";
    import { useLocale } from "next-intlayer";
    import type { PropsWithChildren, FC } from "react";
    
    /**
     * Вспомогательная функция для проверки, является ли данный URL внешним.
     * Если URL начинается с http:// или https://, он считается внешним.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * Кастомный компонент Link, который адаптирует атрибут href в зависимости от текущей локали.
     * Для внутренних ссылок он использует `getLocalizedUrl` для добавления префикса локали к URL (например, /fr/about).
     * Это гарантирует, что навигация остается в контексте той же локали.
     */
    export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
      href,
      children,
      ...props
    }) => {
      const { locale } = useLocale();
      const isExternalLink = checkIsExternalLink(href.toString());
    
      // Если ссылка внутренняя и указан валидный href, получаем локализованный URL.
      const hrefI18n: NextLinkProps["href"] =
        href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
    
      return (
        <NextLink href={hrefI18n} {...props}>
          {children}
        </NextLink>
      );
    };
    

    Как это работает

    • Определение внешних ссылок:
      Вспомогательная функция checkIsExternalLink определяет, является ли URL внешним. Внешние ссылки остаются без изменений, так как они не требуют локализации.

    • Получение текущей локали:
      Хук useLocale предоставляет текущую локаль (например, fr для французского).

    • Локализация URL:
      Для внутренних ссылок (т. е. не внешних) используется getLocalizedUrl для автоматического добавления префикса текущей локали к URL. Это означает, что если ваш пользователь находится на французской версии сайта, передача /about в качестве href преобразует его в /fr/about.

    • Возврат ссылки:
      Компонент возвращает элемент <a> с локализованным URL, обеспечивая соответствие навигации локали.

    Интегрируя этот компонент Link во все приложение, вы поддерживаете согласованный и учитывающий язык пользовательский интерфейс, а также извлекаете выгоду из улучшенного SEO и удобства использования.

12. 12

    Получение текущей локали в Server Actions

    Необязательно

    Если вам нужна активная локаль внутри Server Action (например, для локализации электронных писем или запуска логики, зависящей от локали), вызовите getLocale из next-intlayer/server:

    src/app/actions/getLocale.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    "use server";
    
    import { getLocale } from "next-intlayer/server";
    
    export const myServerAction = async () => {
      const locale = await getLocale();
    
      // Сделайте что-нибудь с локалью
    };
    

    Функция getLocale следует каскадной стратегии для определения локали пользователя:

    1. Сначала она проверяет заголовки запроса на наличие значения локали, которое могло быть установлено прокси.
    2. Если локаль не найдена в заголовках, она ищет локаль, сохраненную в куки.
    3. Если куки не найдены, она пытается определить предпочтительный язык пользователя по настройкам его браузера.
    4. В крайнем случае она возвращается к настроенной в приложении локали по умолчанию.

    Это гарантирует выбор наиболее подходящей локали на основе доступного контекста.

13. 13

    Оптимизация размера вашего бандла

    Необязательно

    При использовании next-intlayer словари по умолчанию включаются в бандл для каждой страницы. Для оптимизации размера бандла Intlayer предоставляет дополнительный плагин SWC, который интеллектуально заменяет вызовы useIntlayer с помощью макросов. Это гарантирует, что словари включаются в бандлы только для тех страниц, которые их действительно используют.

    Чтобы включить эту оптимизацию, установите пакет @intlayer/swc. После установки next-intlayer автоматически обнаружит и начнет использовать плагин:

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm install @intlayer/swc --save-dev
    

    Примечание: Эта оптимизация доступна только для Next.js 13 и выше.

    Примечание: Этот пакет не устанавливается по умолчанию, так как плагины SWC всё ещё являются экспериментальными в Next.js. Это может измениться в будущем.

    Примечание: Если вы установите опцию importMode: 'dynamic' или importMode: 'fetch' (в конфигурации dictionary), она будет полагаться на Suspense, поэтому вам придется обернуть ваши вызовы useIntlayer в границу Suspense. Это означает, что вы не сможете использовать useIntlayer непосредственно на верхнем уровне вашего компонента Page / Layout.

14. 14

    Извлечение содержимого ваших компонентов

    Необязательно

    Если у вас есть существующая кодовая база, преобразование тысяч файлов может занять много времени.

    Чтобы упростить этот процесс, Intlayer предлагает компилятор / экстрактор для преобразования ваших компонентов и извлечения содержимого.

    Чтобы настроить его, вы можете добавить раздел compiler в ваш файл intlayer.config.ts:

    intlayer.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Остальная часть вашей конфигурации
      compiler: {
        /**
         * Указывает, должен ли быть включен компилятор.
         */
        enabled: true,
    
        /**
         * Определяет путь к выходным файлам
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Указывает, должны ли компоненты сохраняться после преобразования. Таким образом, компилятор можно запустить только один раз для преобразования приложения, а затем удалить.
         */
        saveComponents: false,
    
        /**
         * Префикс ключа словаря
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Команда извлеченияКомпилятор Babel

    Запустите экстрактор для преобразования компонентов и извлечения содержимого

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm install @intlayer/babel --save-dev
    

    babel.config.js

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    const {
      intlayerExtractBabelPlugin,
      getExtractPluginOptions,
    } = require("@intlayer/babel");
    
    module.exports = {
      presets: ["next/babel"],
      plugins: [
        // Извлечение содержимого из компонентов в словари
        [intlayerExtractBabelPlugin, getExtractPluginOptions()],
      ],
    };
    

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm run build # Или npm run dev
    

Отслеживание изменений словарей в Turbopack

При использовании Turbopack в качестве сервера разработки с помощью команды next dev изменения в словарях по умолчанию не будут обнаруживаться автоматически.

Это ограничение возникает из-за того, что Turbopack не может запускать плагины webpack параллельно для мониторинга изменений в ваших файлах контента. Чтобы обойти это, вам нужно будет использовать команду intlayer watch, чтобы одновременно запустить сервер разработки и наблюдатель за сборкой Intlayer.

{
  // ... Ваши существующие конфигурации package.json
  "scripts": {
    // ... Ваши существующие конфигурации скриптов
    "dev": "intlayer watch --with 'next dev'",
  },
}

Если вы используете next-intlayer@<=6.x.x, вам нужно оставить флаг --turbopack, чтобы приложение Next.js 16 корректно работало с Turbopack. Мы рекомендуем использовать next-intlayer@>=7.x.x, чтобы избежать этого ограничения.

Настройка TypeScript

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

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

{
  // ... Ваши существующие конфигурации TypeScript
  "include": [
    // ... Ваши существующие конфигурации TypeScript
    ".intlayer/**/*.ts", // Включить автоматически сгенерированные типы
  ],
}

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

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

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

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

Расширение VS Code

Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное расширение Intlayer для VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автодополнение для ключей перевода.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Встроенный предварительный просмотр переведенного контента.
• Быстрые действия для легкого создания и обновления переводов.

Более подробную информацию о том, как использовать расширение, можно найти в документации расширения Intlayer для VS Code.

Идите дальше

Чтобы пойти дальше, вы можете внедрить визуальный редактор или экстернализировать ваш контент с помощью CMS.

Часто задаваемые вопросы