Przetłumacz swoją stronę Next.js 16 (bez [locale] w ścieżce) za pomocą Intlayer | Internationalization (i18n)

Zobacz Szablon aplikacji na GitHubie.

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna, open-source biblioteka do internacjonalizacji (i18n) zaprojektowana, aby upraszczać wielojęzyczne wsparcie we współczesnych aplikacjach webowych. Intlayer bezproblemowo integruje się z najnowszym frameworkiem Next.js 16, w tym z jego potężnym App Router. Jest zoptymalizowany do współpracy z Server Components w celu wydajnego renderowania i jest w pełni kompatybilny z Turbopack.

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami przy użyciu deklaratywnych słowników na poziomie komponentu.
• Dynamicznie lokalizować metadane, trasy i treści.
• Uzyskiwać dostęp do tłumaczeń zarówno w komponentach po stronie klienta, jak i po stronie serwera.
• Zapewnić wsparcie TypeScript poprzez automatycznie generowane typy, poprawiające autouzupełnianie i wykrywanie błędów.
• Skorzystaj z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie locale.

Intlayer jest kompatybilny z Next.js 12, 13, 14 i 16. Jeśli używasz Page Router w Next.js, możesz odnieść się do tego poradnika. Dla Next.js 12, 13, 14 z App Router odnieś się do tego poradnika.

Krok po kroku: konfiguracja Intlayer w aplikacji Next.js

Krok 1: Zainstaluj zależności

Zainstaluj niezbędne pakiety używając npm:

npm install intlayer next-intlayernpx intlayer init

• intlayer

  Pakiet rdzeniowy, który dostarcza narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilacji oraz poleceń CLI.

• next-intlayer

Pakiet integrujący Intlayer z Next.js. Zapewnia context providers i hooki do internacjonalizacji w Next.js. Dodatkowo zawiera plugin Next.js do integracji Intlayer z Webpack lub Turbopack, a także proxy do wykrywania preferowanej lokalizacji użytkownika, zarządzania cookie i obsługi przekierowań URL.

Krok 2: Skonfiguruj swój projekt

Oto końcowa struktura, którą utworzymy:

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Jeśli nie chcesz routingu lokalizacji, intlayer może być użyty jako prosty provider / hook. Zobacz ten przewodnik, aby uzyskać więcej informacji.

Create a config file to configure the languages of your application:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Twoje pozostałe locales    ],    defaultLocale: Locales.ENGLISH,  },  routing: {    mode: "search-params", // lub `no-prefix` - Przydatne do wykrywania w middleware  },};export default config;

Poprzez ten plik konfiguracyjny możesz ustawić lokalizowane adresy URL, przekierowania proxy, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i inne. Aby uzyskać pełną listę dostępnych parametrów, zapoznaj się z dokumentacją konfiguracji.

Krok 3: Integracja Intlayer z konfiguracją Next.js

Skonfiguruj swoje środowisko Next.js, aby używało Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opcje konfiguracji tutaj */};export default withIntlayer(nextConfig);

Wtyczka Next.js withIntlayer() służy do integracji Intlayer z Next.js. Zapewnia budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w środowiskach Webpack lub Turbopack. Dodatkowo udostępnia aliasy w celu optymalizacji wydajności i zapewnia kompatybilność z komponentami po stronie serwera.

Funkcja withIntlayer() jest funkcją zwracającą Promise. Pozwala przygotować słowniki Intlayer przed rozpoczęciem procesu build. Jeśli chcesz użyć jej razem z innymi wtyczkami, możesz użyć await. Przykład:

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

Jeśli chcesz użyć go synchronicznie, możesz skorzystać z funkcji withIntlayerSync(). Przykład:

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

Intlayer automatycznie wykrywa, czy Twój projekt używa webpack czy Turbopack, na podstawie flag wiersza poleceń --webpack, --turbo lub --turbopack, oraz Twojej obecnej wersji Next.js.

Ponieważ next>=16, jeśli używasz Rspack, musisz wyraźnie wymusić użycie konfiguracji webpack przez Intlayer, wyłączając Turbopack:

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

Krok 4: Zdefiniuj dynamiczne trasy lokalizacji

Usuń całą zawartość RootLayout i zastąp ją następującym kodem:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Krok 5: Zadeklaruj swoje treści

Utwórz i zarządzaj deklaracjami treści, aby przechowywać tłumaczenia:

import { t, type Dictionary } from "intlayer";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      pl: "Tytuł mojego projektu",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      pl: "Poznaj naszą innowacyjną platformę zaprojektowaną, aby usprawnić przepływ pracy i zwiększyć produktywność.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      pl: ["innowacja", "produktywność", "przepływ pracy", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      pl: ["innowacja", "produktywność", "przepływ pracy", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },} as Dictionary<Metadata>;export default metadataContent;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      pl: "Tytuł mojego projektu",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      pl: "Odkryj naszą innowacyjną platformę zaprojektowaną, aby usprawnić przepływ pracy i zwiększyć produktywność.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      pl: "Odkryj naszą innowacyjną platformę stworzoną, aby uprościć przepływ pracy i zwiększyć produktywność.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra su plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      pl: ["innowacja", "produktywność", "przepływ pracy", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

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

Twoje deklaracje zawartości mogą być zdefiniowane w dowolnym miejscu aplikacji, pod warunkiem że zostaną umieszczone w katalogu contentDir (domyślnie ./src) i mają odpowiednie rozszerzenie pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Po więcej informacji odwołaj się do dokumentacji pliku deklaracji zawartości.

Krok 6: Wykorzystanie zawartości w kodzie

Uzyskaj dostęp do swoich słowników zawartości w całej aplikacji:

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

• IntlayerClientProvider służy do dostarczania locale komponentom po stronie klienta. Można go umieścić w dowolnym komponencie nadrzędnym, w tym w layout. Jednak zaleca się umieszczenie go w layout, ponieważ Next.js współdzieli kod layoutu między stronami, co jest bardziej wydajne. Używając IntlayerClientProvider w layout, unikasz ponownej inicjalizacji dla każdej strony, poprawiając wydajność i utrzymując spójny kontekst lokalizacji w całej aplikacji.

• IntlayerServerProvider jest używany do dostarczania locale dzieciom po stronie serwera. Nie można go umieścić w layoucie.

  Layout i page nie mogą współdzielić wspólnego kontekstu serwera, ponieważ system kontekstu serwera opiera się na magazynie danych dla każdego żądania (poprzez mechanizm React's cache), powodując, że każdy "kontekst" jest tworzony na nowo dla różnych segmentów aplikacji. Umieszczenie providera we wspólnym layoucie złamałoby tę izolację, uniemożliwiając poprawne propagowanie wartości kontekstu serwera do twoich komponentów serwerowych.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Utwórz deklarację powiązanej treści  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"); // Utwórz deklarację powiązanej zawartości  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

Jeśli chcesz użyć swojej zawartości w atrybucie typu string, takim jak alt, title, href, aria-label itp., musisz wywołać wartość funkcji, na przykład:

<img src={content.image.src.value} alt={content.image.value} />

Aby dowiedzieć się więcej o hooku useIntlayer, zapoznaj się z dokumentacją.

(Opcjonalnie) Krok 7: Skonfiguruj proxy do wykrywania preferowanej lokalizacji użytkownika

Skonfiguruj proxy, aby wykrywało preferowaną lokalizację użytkownika:

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

intlayerProxy jest używany do wykrywania preferowanego języka użytkownika i przekierowywania go na odpowiedni URL, zgodnie z konfiguracją. Dodatkowo umożliwia zapisanie preferowanego języka użytkownika w ciasteczku.

Jeśli potrzebujesz łączyć kilka proxy razem (na przykład intlayerProxy z uwierzytelnianiem lub niestandardowymi proxy), Intlayer udostępnia teraz helper o nazwie multipleProxies.

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

(Opcjonalnie) Krok 8: Zmień język swojej zawartości

Aby zmienić język treści w Next.js, zalecanym sposobem jest użycie komponentu Link do przekierowania użytkowników na odpowiednio zlokalizowaną stronę. Komponent Link umożliwia prefetching, co pomaga uniknąć pełnego przeładowania strony.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale({    onChange: () => window.location.reload(),  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Skrót lokalizacji — np. FR */}              {localeItem}            </span>            <span>              {/* Nazwa języka w jego własnym locale — np. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Nazwa języka w bieżącym locale — np. "Francés" jeśli bieżące locale to Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Język w wersji angielskiej — np. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Alternatywnym sposobem jest użycie funkcji setLocale dostarczonej przez hook useLocale. Ta funkcja nie pozwala na prefetching strony. Zobacz dokumentację hooka useLocale po więcej szczegółów.

Odnośniki w dokumentacji:

• useLocale hook
• getLocaleName hook
• getLocalizedUrl hook
• getHTMLTextDir hook
• hrefLang atrybut
• lang atrybut
• dir atrybut
• aria-current atrybut

(Opcjonalnie) Krok 9: Pobierz bieżący locale w Server Actions

Jeśli potrzebujesz aktywnego locale wewnątrz Server Action (np. do lokalizowania e-maili lub uruchamiania logiki zależnej od locale), wywołaj getLocale z next-intlayer/server:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Zrób coś z locale};

Funkcja getLocale stosuje strategię kaskadową, aby określić locale użytkownika:

1. Najpierw sprawdza nagłówki żądania w poszukiwaniu wartości locale, która mogła zostać ustawiona przez proxy
2. Jeśli w nagłówkach nie znaleziono locale, szuka wartości locale przechowywanej w cookies
3. Jeśli nie znaleziono cookie, próbuje wykryć preferowany język użytkownika na podstawie ustawień przeglądarki
4. W ostateczności używa domyślnego locale skonfigurowanego w aplikacji

Zapewnia to wybór najbardziej odpowiedniej lokalizacji w oparciu na dostępnym kontekście.

(Opcjonalnie) Krok 10: Optymalizacja rozmiaru bundla

Podczas używania next-intlayer, słowniki są domyślnie dołączane do bundla dla każdej strony. Aby zoptymalizować rozmiar bundla, Intlayer udostępnia opcjonalny plugin SWC, który inteligentnie zastępuje wywołania useIntlayer za pomocą makr. Dzięki temu słowniki są dołączane tylko do bundli stron, które faktycznie ich używają.

Aby włączyć tę optymalizację, zainstaluj pakiet @intlayer/swc. Po zainstalowaniu next-intlayer automatycznie wykryje i użyje pluginu:

npm install @intlayer/swc --save-devnpx intlayer init

Uwaga: Ta optymalizacja jest dostępna tylko dla Next.js 13 i nowszych.

Uwaga: Ten pakiet nie jest instalowany domyślnie, ponieważ wtyczki SWC są w Next.js wciąż eksperymentalne. Może to ulec zmianie w przyszłości.

Uwaga: Jeśli ustawisz opcję na importMode: 'dynamic' lub importMode: 'live', będzie to polegać na Suspense, więc będziesz musiał otoczyć wywołania useIntlayer granicą Suspense. To oznacza, że nie będziesz mógł używać useIntlayer bezpośrednio na najwyższym poziomie komponentu Page lub Layout.

Monitorowanie zmian słowników w Turbopack

Jeśli używasz Turbopack jako serwera deweloperskiego z poleceniem next dev, zmiany w słownikach nie będą domyślnie wykrywane automatycznie.

To ograniczenie wynika z faktu, że Turbopack nie może uruchamiać wtyczek webpack równolegle w celu monitorowania zmian w plikach z treścią. Aby to obejść, musisz użyć polecenia intlayer watch, aby uruchomić jednocześnie serwer deweloperski i obserwator budowania Intlayer.

{  // ... Twoje istniejące konfiguracje package.json  "scripts": {    // ... Twoje istniejące konfiguracje skryptów    "dev": "intlayer watch --with 'next dev'",  },}

Jeśli używasz next-intlayer@<=6.x.x, musisz zachować flagę --turbopack, aby aplikacja Next.js 16 działała poprawnie z Turbopack. Zalecamy użycie next-intlayer@>=7.x.x, aby uniknąć tego ograniczenia.

Konfiguracja TypeScript

Intlayer używa module augmentation, aby skorzystać z zalet TypeScript i wzmocnić swoją codebase.

Upewnij się, że Twoja konfiguracja TypeScript zawiera autogenerowane typy.

{  // ... Twoje istniejące konfiguracje TypeScript  "include": [    // ... Twoje istniejące konfiguracje TypeScript    ".intlayer/**/*.ts", // Dołącz auto-generowane typy  ],}

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwoli to uniknąć ich zatwierdzania do Twojego repozytorium Git.

Aby to zrobić, możesz dodać następujące wpisy do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby ulepszyć doświadczenie programistyczne z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer VS Code Extension.

Zainstaluj z VS Code Marketplace

To rozszerzenie udostępnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podglądy inline przetłumaczonej zawartości.
• Szybkie akcje umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.

Aby uzyskać więcej informacji o korzystaniu z rozszerzenia, zapoznaj się z dokumentacją Intlayer VS Code Extension.

Dalsze kroki

Aby pójść dalej, możesz wdrożyć edytor wizualny lub zewnętrznie przechowywać swoją zawartość za pomocą CMS.