Перекладіть ваш вебсайт Next.js 15 за допомогою Intlayer | Інтернаціоналізація (i18n)

Зміст

Що таке Intlayer?

Intlayer, інноваційна бібліотека для інтернаціоналізації (i18n) з відкритим кодом, створена для спрощення багатомовної підтримки в сучасних веб‑додатках. Intlayer плавно інтегрується з останньою версією Next.js 15, включаючи його потужний App Router. Вона оптимізована для роботи з Server Components для ефективного рендерингу і повністю сумісна з Turbopack.

З Intlayer ви можете:

• Легко керувати перекладами за допомогою декларативних словників на рівні компонентів.
• Динамічно локалізувати метадані, маршрути та вміст.
• Отримувати доступ до перекладів як у клієнтських, так і в серверних компонентах.
• Забезпечте підтримку TypeScript за допомогою автогенерованих типів, що покращують автозаповнення та виявлення помилок.
• Отримайте переваги від розширених функцій, таких як динамічне визначення локалі та її перемикання.

Intlayer сумісний з Next.js 12, 13, 14 та 15. Якщо ви використовуєте Next.js Page Router, ви можете звернутися до цього посібника. Для Next.js 12, 13, 14 з App Router зверніться до цього посібника.

Покроковий посібник з налаштування Intlayer у додатку Next.js

Дивіться Application Template на GitHub.

Крок 1: Встановлення залежностей

Встановіть необхідні пакети за допомогою npm:

npm install intlayer next-intlayernpx intlayer init

• intlayer

  Основний пакет, який надає інструменти інтернаціоналізації для управління конфігурацією, перекладів, декларації контенту, транспіляції та команд CLI.

• next-intlayer

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

  Основний пакет, який надає інструменти інтернаціоналізації для управління конфігурацією, перекладу, декларації контенту, транспіляції та CLI-команд.

• next-intlayer

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

Крок 2: Налаштуйте свій проєкт

Here is the final structure that we will make:

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

Створіть файл конфігурації, щоб налаштувати мови вашого застосунку:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Інші ваші локалі
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Через цей файл конфігурації ви можете налаштувати локалізовані URL-адреси, перенаправлення через middleware, назви cookie, розташування та розширення ваших декларацій контенту, відключити логи Intlayer у консолі та інше. Для повного переліку доступних параметрів зверніться до документації з конфігурації.

Крок 3: Інтеграція Intlayer у конфігурацію Next.js

Налаштуйте конфігурацію Next.js для використання Intlayer:

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. Додатково він надає aliases для оптимізації продуктивності та забезпечує сумісність із серверними компонентами.

Функція withIntlayer() повертає проміс. Вона дозволяє підготувати словники Intlayer перед початком збірки. Якщо ви хочете використовувати її з іншими плагінами, ви можете використати await. Приклад:

tsx

Копіювати вміст

Копіювати код

Скопіюйте код у буфер обміну

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

Якщо ви хочете використовувати його синхронно, ви можете скористатися функцією withIntlayerSync(). Приклад:

tsx

Копіювати вміст

Копіювати код

Скопіюйте код у буфер обміну

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

Крок 4: Визначення динамічних маршрутів локалі

Видаліть усе з RootLayout і замініть на наступний код:

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>.

Щоб реалізувати динамічну маршрутизацію, вкажіть шлях для локалі, додавши новий layout у ваш каталог [locale]:

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 у вашому браузері. Щоб встановити локаль за замовчуванням для кореневої сторінки, зверніться до налаштування middleware у кроці 7.

Далі реалізуйте функцію generateStaticParams у Layout вашого застосунку.

export { generateStaticParams } from "next-intlayer"; // Line to insert

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... Решта коду */
};

export default LocaleLayout;

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

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

Крок 5: Оголосіть контент

Створіть і керуйте оголошеннями контенту для збереження перекладів:

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        uk: "Почніть із редагування",
        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}).

Для детальнішої інформації зверніться до документації щодо декларації контенту.

Крок 6: Використання контенту у коді

Отримуйте доступ до словників контенту у всьому застосунку:

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 використовується для передачі локалі клієнтським компонентам. Його можна розмістити в будь-якому батьківському компоненті, включно з layout. Однак рекомендовано розміщувати його в layout, оскільки Next.js ділиться кодом layout між сторінками, що робить це ефективнішим. Використовуючи IntlayerClientProvider у layout, ви уникаєте повторної ініціалізації для кожної сторінки, покращуєте продуктивність і підтримуєте послідовний контекст локалізації у всьому вашому додатку.

• IntlayerServerProvider використовується для надання локалі серверним дочірнім компонентам. Його не можна встановлювати в layout.

  Layout і сторінка не можуть спільно використовувати спільний server context, оскільки система server context базується на сховищі даних для кожного запиту (через механізм React's cache), що призводить до повторного створення кожного "контексту" для різних сегментів додатку. Розміщення провайдера в загальному layout порушить цю ізоляцію і не дозволить правильно передавати значення server context вашим server components.

  Layout і page не можуть мати спільного server context, оскільки система server context базується на сховищі даних на запит (через механізм React's cache), внаслідок чого кожен «context» створюється заново для різних сегментів застосунку. Розміщення провайдера в спільному layout порушило б цю ізоляцію й не дозволило б коректно пропагувати значення server context до ваших server components.

"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>
  );
};

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, див. документацію.

(Необов'язково) Крок 7: Налаштування middleware для визначення локалі

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

export { intlayerMiddleware as middleware } from "next-intlayer/middleware";

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

intlayerMiddleware використовується для визначення переважної мови користувача та перенаправлення його на відповідний URL, як вказано в конфігурації. Крім того, він дозволяє зберігати перевагу мови користувача в cookie.

Якщо вам потрібно зв'язати кілька middleware разом (наприклад, intlayerMiddleware з автентифікацією або кастомними middleware), Intlayer тепер надає хелпер під назвою multipleMiddlewares.

import {  multipleMiddlewares,  intlayerMiddleware,} from "next-intlayer/middleware";import { customMiddleware } from "@utils/customMiddleware";export const middleware = multipleMiddlewares([  intlayerMiddleware,  customMiddleware,]);

(Необов'язково) Крок 8: Інтернаціоналізація ваших метаданих

Якщо ви хочете інтернаціоналізувати свої метадані, такі як заголовок вашої сторінки, ви можете використати функцію generateMetadata, яку надає Next.js. Всередині неї ви можете отримати вміст через функцію getIntlayer, щоб перекласти свої метадані.

import { type Dictionary, t } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      uk: "Створити додаток Next",
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      uk: "Згенеровано за допомогою create next app",
      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;

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,
    },
  };
};

// ... Rest of the code

Зверніть увагу, що функція getIntlayer, імпортована з next-intlayer, повертає ваш контент, обгорнутий в IntlayerNode, що дозволяє інтеграцію з візуальним редактором. Натомість функція getIntlayer, імпортована з intlayer, повертає ваш контент без додаткових властивостей.

Альтернативно, ви можете використовувати функцію getTranslation для оголошення ваших метаданих. Проте рекомендується використовувати файли декларацій контенту, щоб автоматизувати переклад ваших метаданих і згодом винести контент.

import {
  type IConfigLocales,
  getTranslation,
  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 t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    title: t<string>({
      uk: "Мій заголовок",
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      uk: "Мій опис",
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };
};

// ... Rest of the code

Дізнайтеся більше про оптимізацію метаданих в офіційній документації Next.js.

(Необов'язково) Крок 9: Інтернаціоналізація вашого sitemap.xml та robots.txt

Щоб інтернаціоналізувати sitemap.xml та robots.txt, ви можете використати функцію getMultilingualUrls, надану Intlayer. Ця функція дозволяє генерувати багатомовні URL-адреси для вашого sitemap.

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;

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;

Дізнайтеся більше про оптимізацію sitemap у офіційній документації Next.js. Дізнайтеся більше про оптимізацію robots.txt у офіційній документації Next.js.

(Необов'язково) Крок 10: Зміна мови вашого контенту

Щоб змінити мову вашого контенту в Next.js, рекомендується використовувати компонент Link для перенаправлення користувачів на відповідну локалізовану сторінку. Компонент Link дозволяє виконувати prefetch сторінки, що допомагає уникнути повного перезавантаження сторінки.

"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 // Забезпечить, що кнопка "назад" у браузері перенаправлятиме на попередню сторінку
          >
  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>
  );
};
            <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. Ця функція не дозволяє робити prefetch сторінки. Див. документацію по useLocale hook для детальнішої інформації.

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

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Rest of the codeconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>Change to French</button>);

Посилання на документацію:

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

(Необов'язково) Крок 11: Створення локалізованого компонента Link

Щоб гарантувати, що навігація вашого додатку враховує поточну локаль, ви можете створити кастомний компонент Link. Цей компонент автоматично додає префікс внутрішнім URL відповідно до поточної мови. Наприклад, коли франкофонний користувач клікає на посилання на сторінку "About", він буде перенаправлений на /fr/about замість /about.

Ця поведінка корисна з кількох причин:

• SEO та User Experience: Локалізовані URL допомагають пошуковим системам правильно індексувати мовно-специфічні сторінки та надавати користувачам контент їхньою бажаною мовою.
• Consistency: Використовуючи локалізоване посилання в усьому додатку, ви гарантуєте, що навігація залишатиметься в межах поточної локалі, запобігаючи несподіваним перемиканням мови.
• Підтримуваність: Централізація логіки локалізації в одному компоненті спрощує керування URL-адресами, роблячи вашу codebase легшою для підтримки та розширення у міру зростання застосунку.

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

"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 для автоматичного додавання префіксу з поточною локаллю. Це означає, що якщо ваш користувач використовує французьку, передання /about як href перетвориться на /fr/about.

• Повернення посилання:
  Компонент повертає елемент <a> з локалізованим URL, гарантуючи, що навігація відповідає локалі.

Інтегруючи цей компонент Link у вашому застосунку, ви підтримуєте узгоджений і орієнтований на мову досвід користувача, а також отримуєте переваги покращеного SEO та зручності використання.

(Необов'язково) Крок 12: Отримати поточну локаль у Server Actions

Якщо вам потрібна активна локаль всередині Server Action (наприклад, щоб локалізувати електронні листи або виконувати логіку, залежну від локалі), викличте getLocale з next-intlayer/server:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Виконайте дію з локаллю};

Функція getLocale дотримується каскадної стратегії для визначення локалі користувача:

1. Спочатку перевіряє заголовки запиту на наявність значення локалі, яке могло бути встановлене middleware
2. Якщо локаль не знайдена в заголовках, вона шукає локаль у cookies
3. Якщо cookie не знайдено, вона намагається визначити мову, переважну для користувача, за налаштуваннями браузера
4. Як останній варіант, вона повертається до локалі за замовчуванням, налаштованої в застосунку

Це забезпечує вибір найвідповіднішої локалі на основі наявного контексту.

(Необов'язково) Крок 13: Оптимізуйте розмір bundle

Під час використання next-intlayer словники за замовчуванням включаються в bundle для кожної сторінки. Щоб оптимізувати розмір bundle, Intlayer пропонує необов'язковий плагін для SWC, який за допомогою макросів інтелектуально замінює виклики useIntlayer. Це гарантує, що словники будуть включені в bundle лише для сторінок, які їх справді використовують.

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

npm install @intlayer/swc --save-dev

Примітка: Ця оптимізація доступна тільки для Next.js 13 і новіших версій.

Примітка: Цей пакет не встановлюється за замовчуванням, оскільки SWC-плагіни в Next.js все ще є експериментальними. Це може змінитися в майбутньому.

Примітка: Якщо ви встановите опцію як importMode: 'dynamic' або importMode: 'fetch' (in the dictionary configuration), це буде покладатися на Suspense, тож вам доведеться обгорнути виклики useIntlayer у межу Suspense. Це означає, що ви не зможете використовувати useIntlayer безпосередньо на верхньому рівні вашого компоненту Page / Layout.

Слідкування за змінами словників у Turbopack

При використанні Turbopack як серверу розробки за допомогою команди next dev --turbopack, зміни в словниках за замовчуванням не будуть автоматично виявлятися.

Це обмеження виникає тому, що Turbopack не може запускати webpack-плагіни паралельно для відстеження змін у ваших файлах контенту. Щоб обійти це, потрібно використовувати команду intlayer watch, яка дозволяє одночасно запускати сервер розробки та спостерігача збірки Intlayer.

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

Налаштування TypeScript

Intlayer використовує module augmentation, щоб скористатися перевагами TypeScript і зробити вашу codebase надійнішою.

Переконайтеся, що ваша конфігурація TypeScript включає автогенеровані типи.

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

Налаштування Git

Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволяє уникнути додавання їх у ваш Git-репозиторій.

Для цього ви можете додати наступні інструкції до файлу .gitignore:

# Ігнорувати файли, згенеровані Intlayer.intlayer

Розширення для VS Code

Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне розширення Intlayer для VS Code.

Встановити з Marketplace для VS Code

Це розширення надає:

• Автодоповнення для ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудований перегляд перекладеного контенту.
• Швидкі дії для зручного створення та оновлення перекладів.

Для детальнішої інформації про використання розширення зверніться до документації розширення Intlayer для VS Code.

Далі

Щоб розширити можливості, ви можете реалізувати візуальний редактор або винести свій контент, використовуючи CMS.