Creation:2024-12-06Last update:2026-05-31

    Przetłumacz swoją stronę Next.js 14 i App Router za pomocą Intlayer | Internacjonalizacja (i18n)

    ide.intlayer.org

    Spis treści

    Dlaczego Interlayer zamiast alternatyw?

    W porównaniu do głównych rozwiązań, takich jak next-intl czy i18next, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

    Pełne pokrycie Next.js

    Intlayer jest zoptymalizowany do współpracy z Server Components w celu wydajnego renderowania i jest w pełni kompatybilny z Turbopack. Nie blokuje renderowania statycznego i oferuje oprogramowanie pośredniczące oraz wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).

    Intlayer jest kompatybilny z Next.js 12, 13, 14, 15 i 16. Jeśli używasz routera Next.js Pages Router, możesz zapoznać się z tym [przewodnikiem] (/pl/doc/environment/nextjs/next-with-page-router). Routing lokalny jest przydatny ze względu na SEO, rozmiar bundle'a i wydajność. Jeśli go nie potrzebujesz, możesz zapoznać się z tym przewodnikiem. W przypadku Next.js 12, 13, 14 i 15 z App Router zapoznaj się z tym [przewodnikiem] (/pl/doc/environment/nextjs/14).

    Rozmiar bundle'a

    Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga zmniejszyć rozmiary bundle'a i stron nawet o 50%.

    Łatwość konserwacji

    Określanie zakresu zawartości aplikacji ułatwia konserwację aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest w pełni napisany, aby zapewnić dokładność treści.

    Agent AI

    Wspólna lokalizacja treści zmniejsza potrzebny kontekst dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak CLI do sprawdzania brakujących tłumaczeńLSP, MCP i umiejętności agenta, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.

    Automatyzacja

    Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także kompilator do automatyzacji ekstrakcji treści, a także [platformę internetową] (/pl/doc/concept/cms), która pomaga tłumaczyć w tle.

    Wydajność

    Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.

    Skalowanie bez użycia dewelopera

    Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia samodzielny edytor wizualny i pełny CMS, który pomoże Ci zarządzać wielojęzyczną treścią w w czasie rzeczywistym, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.

    Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Next.js

    Zobacz Szablon aplikacji na GitHub.

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

      bash
      npm install intlayer next-intlayernpx intlayer init

      • intlayer

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

      • next-intlayer

        Pakiet integrujący Intlayer z Next.js. Zapewnia dostawców kontekstu oraz hooki do internacjonalizacji w Next.js. Dodatkowo zawiera wtyczkę Next.js do integracji Intlayer z Webpack lub Turbopack, a także middleware do wykrywania preferowanego języka użytkownika, zarządzania ciasteczkami oraz obsługi przekierowań URL.

    2. Skonfiguruj swój projekt

      Here is the final structure that we will make:

      bash
      .├── 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.

      Utwórz plik konfiguracyjny, aby skonfigurować języki swojej aplikacji:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Twoje inne locale
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Poprzez ten plik konfiguracyjny możesz ustawić lokalizowane adresy URL, przekierowania w middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji zawartości, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracyjnej.

    3. Zintegruj Intlayer w konfiguracji Next.js

      Skonfiguruj swoje środowisko Next.js, aby korzystało z Intlayer:

      next.config.mjs
      import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {};export default withIntlayer(nextConfig);
      Wtyczka Next.js withIntlayer() służy do integracji Intlayer z Next.js. Zapewnia budowanie plików deklaracji zawartości oraz monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w środowiskach Webpack lub Turbopack. Dodatkowo dostarcza aliasy optymalizujące wydajność oraz zapewnia kompatybilność z komponentami serwerowymi.

      Funkcja withIntlayer() jest funkcją zwracającą promise. Jeśli chcesz użyć jej z innymi wtyczkami, możesz ją awaitować. Przykład:

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

    4. Skonfiguruj Middleware do wykrywania lokalizacji

      Skonfiguruj middleware, aby wykrywać preferowaną lokalizację użytkownika:

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

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
      intlayerMiddleware służy do wykrywania preferowanej lokalizacji użytkownika i przekierowywania go na odpowiedni URL, zgodnie z konfiguracją. Dodatkowo umożliwia zapisywanie preferowanej lokalizacji użytkownika w ciasteczku.
      Dostosuj parametr matcher, aby odpowiadał trasom Twojej aplikacji. Po więcej szczegółów odsyłamy do dokumentacji Next.js dotyczącej konfiguracji matcher.
      Jeśli potrzebujesz połączyć kilka middleware'ów razem (na przykład intlayerMiddleware z uwierzytelnianiem lub niestandardowymi middleware'ami), Intlayer udostępnia teraz pomocnika o nazwie multipleMiddlewares.
      ts
      import {  multipleMiddlewares,  intlayerMiddleware,} from "next-intlayer/middleware";import { customMiddleware } from "@utils/customMiddleware";export const middleware = multipleMiddlewares([  intlayerMiddleware,  customMiddleware,]);

    5. Zdefiniuj dynamiczne trasy lokalizacji

      Usuń wszystko z RootLayout i zastąp to następującym kodem:

      src/app/layout.tsx
      import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // Nadal możesz opakować dzieci innymi providerami, takimi jak `next-themes`, `react-query`, `framer-motion` itd.
  <>{children}</>
);

export default RootLayout;
      Pozostawienie komponentu RootLayout pustym pozwala na ustawienie atrybutów lang oraz dir na tagu <html>.

      Aby zaimplementować dynamiczne routowanie, podaj ścieżkę dla lokalizacji, dodając nowy layout w katalogu [locale]:

      src/app/[locale]/layout.tsx
      import {
  type Next14LayoutIntlayer,
  IntlayerClientProvider,
} from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => (
  <html lang={locale} dir={getHTMLTextDir(locale)}>
    <body className={inter.className}>
      <IntlayerClientProvider locale={locale}>
        {children}
      </IntlayerClientProvider>
    </body>
  </html>
);

export default LocaleLayout;
      Segment ścieżki [locale] jest używany do określenia lokalizacji. Przykład: /en-US/about odnosi się do en-US, a /fr/about do fr.
      Na tym etapie napotkasz błąd: Error: Missing <html> and <body> tags in the root layout.. Jest to oczekiwane, ponieważ plik /app/page.tsx nie jest już używany i można go usunąć. Zamiast tego segment ścieżki [locale] aktywuje stronę /app/[locale]/page.tsx. W konsekwencji strony będą dostępne pod ścieżkami takimi jak /en, /fr, /es w Twojej przeglądarce. Aby ustawić domyślną lokalizację jako stronę główną, odwołaj się do konfiguracji middleware w kroku 4.

      Następnie zaimplementuj funkcję generateStaticParams w układzie (Layout) swojej aplikacji.

      src/app/[locale]/layout.tsx
      export { generateStaticParams } from "next-intlayer"; // Linia do dodania

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => {
  /*... Reszta kodu*/
};

export default LocaleLayout;
      generateStaticParams zapewnia, że Twoja aplikacja prekompiluje niezbędne strony dla wszystkich lokalizacji, zmniejszając obciążenie podczas działania i poprawiając doświadczenie użytkownika. Po więcej szczegółów odsyłamy do dokumentacji Next.js dotyczącej generateStaticParams.

    6. Zadeklaruj swoją zawartość

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

      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;
      Twoje deklaracje treści mogą być definiowane w dowolnym miejscu w aplikacji, pod warunkiem, że zostaną umieszczone w katalogu contentDir (domyślnie ./src). I będą miały rozszerzenie pliku deklaracji treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs}).
      Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją deklaracji treści.

    7. Wykorzystaj treść w swoim kodzie

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

      src/app/[locale]/page.tsx
      import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type Next14PageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const Page: Next14PageIntlayer = ({ params: { locale } }) => {
  const content = useIntlayer("page", locale);

  return (
    <>
      <p>
        {content.getStarted.main}
        <code>{content.getStarted.pageLink}</code>
      </p>

      <IntlayerServerProvider locale={locale}>
        <ServerComponentExample />
        <ClientComponentExample />
      </IntlayerServerProvider>
    </>
  );
};

export default Page;
      • IntlayerClientProvider służy do dostarczania informacji o lokalizacji komponentom po stronie klienta. Może być umieszczony w dowolnym komponencie nadrzędnym, w tym w layoucie. Jednak zaleca się umieszczenie go w layoucie, ponieważ Next.js współdzieli kod layoutu między stronami, co jest bardziej efektywne. Używając IntlayerClientProvider w layoucie, unikasz ponownej inicjalizacji na każdej stronie, co poprawia wydajność i utrzymuje spójny kontekst lokalizacji w całej aplikacji.
      • IntlayerServerProvider służy do dostarczania informacji o lokalizacji komponentom po stronie serwera. Nie może być ustawiony w layoucie.
      Layout i strona 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), co powoduje, że każdy „kontekst” jest tworzony na nowo dla różnych segmentów aplikacji. Umieszczenie providera w wspólnym layoucie złamałoby tę izolację, uniemożliwiając prawidłowe propagowanie wartości kontekstu serwera do Twoich komponentów serwerowych.
      src/components/ClientComponentExample.tsx
      "use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // Utwórz powiązaną deklarację treści

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      src/components/ServerComponentExample.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // Utwórz powiązaną deklarację 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:
      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)}" />
      Aby dowiedzieć się więcej o hooku useIntlayer, zapoznaj się z dokumentacją.

    8. Internacjonalizacja metadanych

      Opcjonalne

      Jeśli chcesz internacjonalizować swoje metadane, takie jak tytuł strony, możesz użyć funkcji generateMetadata dostarczonej przez Next.js. Wewnątrz możesz pobrać zawartość z funkcji getIntlayer, aby przetłumaczyć swoje metadane.

      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 { LocalParams } from "next-intlayer";

export const generateMetadata = ({
  params: { locale },
}: LocalParams): Metadata => {
  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Generuje obiekt zawierający wszystkie adresy URL dla każdego języka.
   *
   * Przykład:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Zwraca
   *  // {
   *  //   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,
    },
  };
};

// ... Reszta kodu
      Zauważ, że funkcja getIntlayer importowana z next-intlayer zwraca Twoją zawartość opakowaną w IntlayerNode, co umożliwia integrację z edytorem wizualnym. Natomiast funkcja getIntlayer importowana z intlayer zwraca Twoją zawartość bezpośrednio, bez dodatkowych właściwości.

      Alternatywnie możesz użyć funkcji getTranslation do deklarowania swoich metadanych. Jednak zaleca się używanie plików deklaracji zawartości, aby zautomatyzować tłumaczenie metadanych i w pewnym momencie wyodrębnić zawartość na zewnątrz.

      src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
      import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalParams } from "next-intlayer";

export const generateMetadata = ({
  params: { locale },
}: LocalParams): Metadata => {
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    title: t<string>({
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };
};

// ... Reszta kodu
      Dowiedz się więcej o optymalizacji metadanych w oficjalnej dokumentacji Next.js.

    9. Internacjonalizacja plików sitemap.xml i robots.txt

      Opcjonalne

      Aby zinternacjonalizować pliki sitemap.xml i robots.txt, możesz użyć funkcji getMultilingualUrls dostarczonej przez Intlayer. Funkcja ta pozwala na generowanie wielojęzycznych URL-i dla Twojej mapy witryny.

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

// Funkcja pobierająca wszystkie wielojęzyczne URL-e z podanej listy
const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

// Definicja reguł dla pliku robots.txt
const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]), // Blokowanie dostępu do stron logowania i rejestracji
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

export default robots;
      Dowiedz się więcej o optymalizacji mapy witryny w oficjalnej dokumentacji Next.js. Dowiedz się więcej o optymalizacji pliku robots.txt w oficjalnej dokumentacji Next.js.

    10. Zmień język swojej zawartości

      Opcjonalne

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

      src/components/LocaleSwitcher.tsx
      "use client";

import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import { type FC } from "react";
import Link from "next/link";

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)}
            hrefLang={localeItem}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // Zapewni, że przycisk "wstecz" w przeglądarce przekieruje do poprzedniej strony
          >
            <span>
              {/* Lokalizacja - np. FR */}
              {localeItem}
            </span>
            <span>
              {/* Język w jego własnej lokalizacji - np. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Język w bieżącym lokalnym ustawieniu - np. Francés przy ustawionym Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Język po angielsku - np. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};
      Alternatywnym sposobem jest użycie funkcji setLocale dostarczonej przez hook useLocale. Ta funkcja nie pozwala na prefetching strony. Szczegóły znajdziesz w dokumentacji hooka useLocale.
      Możesz również ustawić funkcję w opcji onLocaleChange, aby wywołać niestandardową funkcję w momencie zmiany lokalizacji.
      src/components/LocaleSwitcher.tsx
      "use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Reszta koduconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>Zmień na francuski</button>);

      Odwołania do dokumentacji:

    11. Tworzenie lokalizowanego komponentu Link

      Opcjonalne

      Aby zapewnić, że nawigacja w Twojej aplikacji respektuje aktualną lokalizację, możesz stworzyć niestandardowy komponent Link. Ten komponent automatycznie dodaje prefiks z aktualnym językiem do wewnętrznych adresów URL. Na przykład, gdy użytkownik mówiący po francusku kliknie na link do strony "About", zostanie przekierowany na /fr/about zamiast na /about.

      To zachowanie jest przydatne z kilku powodów:

      • SEO i doświadczenie użytkownika: Lokalizowane adresy URL pomagają wyszukiwarkom poprawnie indeksować strony specyficzne dla danego języka oraz dostarczają użytkownikom treści w ich preferowanym języku.
      • Spójność: Korzystając z lokalizowanego linku w całej aplikacji, gwarantujesz, że nawigacja pozostaje w ramach bieżącej lokalizacji, zapobiegając nieoczekiwanym zmianom języka.
      • Utrzymanie: Centralizacja logiki lokalizacji w jednym komponencie upraszcza zarządzanie adresami URL, co sprawia, że baza kodu jest łatwiejsza do utrzymania i rozbudowy wraz z rozwojem aplikacji.

      Poniżej znajduje się implementacja lokalizowanego komponentu Link w 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 { forwardRef, PropsWithChildren, type ForwardedRef } from "react";

/**
 * Funkcja pomocnicza do sprawdzania, czy podany URL jest zewnętrzny.
 * Jeśli URL zaczyna się od http:// lub https://, jest uznawany za zewnętrzny.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Niestandardowy komponent Link, który dostosowuje atrybut href na podstawie aktualnej lokalizacji.
 * Dla linków wewnętrznych używa `getLocalizedUrl`, aby poprzedzić URL lokalizacją (np. /fr/about).
 * Zapewnia to, że nawigacja pozostaje w tym samym kontekście lokalizacji.
 */
export const Link = forwardRef<
  HTMLAnchorElement,
  PropsWithChildren<NextLinkProps>
>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Jeśli link jest wewnętrzny i podano prawidłowy href, pobierz zlokalizowany URL.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} ref={ref} {...props}>
      {children}
    </NextLink>
  );
});

Link.displayName = "Link";

      Jak to działa

      • Wykrywanie linków zewnętrznych:
        Funkcja pomocnicza checkIsExternalLink określa, czy URL jest zewnętrzny. Linki zewnętrzne pozostają niezmienione, ponieważ nie wymagają lokalizacji.

      • Pobieranie bieżącej lokalizacji:
        Hook useLocale dostarcza aktualną lokalizację (np. fr dla języka francuskiego).

      • Lokalizacja URL:
        Dla linków wewnętrznych (czyli nie zewnętrznych) używana jest funkcja getLocalizedUrl, która automatycznie dodaje prefiks z aktualną lokalizacją do URL. Oznacza to, że jeśli użytkownik korzysta z wersji francuskiej, przekazanie /about jako href zostanie przekształcone na /fr/about.

      • Zwracanie linku:
        Komponent zwraca element <a> z lokalizowanym URL, zapewniając spójność nawigacji zgodnie z lokalizacją.

      Integrując ten komponent Link w całej aplikacji, utrzymujesz spójne i świadome językowo doświadczenie użytkownika, a także korzystasz z lepszego SEO i użyteczności.

    12. Pobierz aktualną lokalizację w Server Actions

      Opcjonalne

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

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

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

      1. Najpierw sprawdza nagłówki żądania pod kątem wartości lokalizacji, która mogła zostać ustawiona przez middleware
      2. Jeśli w nagłówkach nie znaleziono lokalizacji, szuka lokalizacji zapisanej w ciasteczkach
      3. Jeśli nie znaleziono ciasteczka, próbuje wykryć preferowany język użytkownika na podstawie ustawień przeglądarki
      4. W ostateczności, używana jest domyślna lokalizacja skonfigurowana w aplikacji

      Zapewnia to wybór najbardziej odpowiedniej lokalizacji na podstawie dostępnego kontekstu.

    13. Optymalizacja rozmiaru bundla

      Opcjonalne

      Podczas korzystania z 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. Zapewnia to, że 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 instalacji next-intlayer automatycznie wykryje i użyje tego pluginu:

      bash
      npm install @intlayer/swc --save-dev
      Uwaga: Ta optymalizacja jest dostępna tylko dla Next.js 13 i nowszych wersji.
      Uwaga: Ten pakiet nie jest instalowany domyślnie, ponieważ wtyczki SWC są nadal eksperymentalne w Next.js. Może się to zmienić w przyszłości.

      Uwaga: Jeśli ustawisz opcję jako importMode: 'dynamic' lub importMode: 'fetch' (in the dictionary configuration), będzie to polegać na Suspense, więc będziesz musiał owinąć wywołania useIntlayer w granicę Suspense. Oznacza to, że nie będziesz mógł używać useIntlayer bezpośrednio na najwyższym poziomie komponentu Strony / Układu.

    Konfiguracja TypeScript

    Intlayer używa rozszerzenia modułów (module augmentation), aby korzystać z zalet TypeScript i wzmocnić Twoją bazę kodu.

    Autouzupełnianie

    Błąd tłumaczenia

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

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

    Konfiguracja Git

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

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

    .gitignore
    # Ignoruj pliki generowane przez Intlayer.intlayer

    Rozszerzenie VS Code

    Aby poprawić swoje doświadczenie w pracy z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

    Zainstaluj z Marketplace VS Code

    To rozszerzenie oferuje:

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

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

    Idź dalej

    Aby pójść dalej, możesz zaimplementować edytor wizualny lub zewnętrznie zarządzać swoją zawartością, korzystając z CMS.

    plaintext
    Next.js
    Next.js 15