Dokumentacja: funkcja t w next-intlayer

Funkcja t w pakiecie next-intlayer jest podstawowym narzędziem do inline'owej internacjonalizacji w Twojej aplikacji Next.js. Pozwala na definiowanie tłumaczeń bezpośrednio w komponentach, co ułatwia wyświetlanie lokalizowanych treści w zależności od aktualnej lokalizacji.

Przegląd

Funkcja t służy do dostarczania tłumaczeń dla różnych lokalizacji bezpośrednio w Twoich komponentach. Przekazując obiekt zawierający tłumaczenia dla każdej obsługiwanej lokalizacji, t zwraca odpowiednie tłumaczenie na podstawie aktualnego kontekstu lokalizacji w Twojej aplikacji Next.js.

Kluczowe funkcje

• Tłumaczenia inline: Idealne do szybkiego, inline'owego tekstu, który nie wymaga oddzielnej deklaracji treści.
• Automatyczny wybór lokalizacji: Automatycznie zwraca tłumaczenie odpowiadające aktualnej lokalizacji.
• Wsparcie TypeScript: Zapewnia bezpieczeństwo typów i autouzupełnianie podczas używania z TypeScript.
• Łatwa integracja: Działa bezproblemowo zarówno w komponentach klienta, jak i serwera w Next.js.

Sygnatura funkcji

typescript
t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string

Parametry

• translations: Obiekt, w którym kluczami są kody lokalizacji (np. en, fr, es), a wartościami odpowiadające im przetłumaczone ciągi znaków.

Zwraca

• Ciąg znaków reprezentujący przetłumaczoną treść dla aktualnej lokalizacji.

Przykłady użycia

Użycie t w komponencie klienta

Upewnij się, że na początku pliku komponentu umieścisz dyrektywę 'use client'; podczas korzystania z t w komponencie po stronie klienta.

"use client";

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

export const ClientComponentExample: FC = () => (
  <p>
    {t({
      en: "This is the content of a client component example",
      fr: "Ceci est le contenu d'un exemple de composant client",
      es: "Este es el contenido d un ejemplo de componente cliente",
    })}
  </p>
);

Używanie t w komponencie serwerowym

import type { FC } from "react";
import { t } from "next-intlayer/server";

export const ServerComponentExample: FC = () => (
  <p>
    {t({
      en: "This is the content of a server component example",
      fr: "Ceci est le contenu d'un exemple de composant serveur",
      es: "Este es el contenido de un ejemplo de componente servidor",
    })}
  </p>
);

Tłumaczenia inline w atrybutach

Funkcja t jest szczególnie przydatna do tłumaczeń inline w atrybutach JSX. Podczas lokalizacji atrybutów takich jak alt, title, href czy aria-label, możesz użyć t bezpośrednio w atrybucie.

<button
  aria-label={t({
    en: "Submit",
    fr: "Soumettre",
    es: "Enviar",
  })}
>
  {t({
    en: "Submit",
    fr: "Soumettre",
    es: "Enviar",
  })}
  <img
    src="/path/to/image"
    alt={t({
      en: "A beautiful scenery",
      fr: "Un beau paysage",
      es: "Un hermoso paisaje",
    })}
  />
</button>

Zaawansowane tematy

Integracja z TypeScript

Funkcja t jest bezpieczna typowo podczas użycia z TypeScript, zapewniając, że wszystkie wymagane lokalizacje są dostarczone.

import type { IConfigLocales } from "intlayer";
import { t } from "next-intlayer";

const translations: IConfigLocales<string> = {
  en: "Welcome",
  fr: "Bienvenue",
  es: "Bienvenido",
};

const greeting = t(translations);

Wykrywanie lokalizacji i kontekst

W next-intlayer bieżąca lokalizacja jest zarządzana przez dostawców kontekstu: IntlayerClientProvider oraz IntlayerServerProvider. Upewnij się, że ci dostawcy otaczają twoje komponenty, a właściwość locale jest poprawnie przekazywana.

Przykład:

import type { FC } from "react";
import type { Locales } from "intlayer";
import { IntlayerClientProvider } from "next-intlayer";
import { IntlayerServerProvider } from "next-intlayer/server";

const Page: FC<{ locale: Locales }> = ({ locale }) => (
  <IntlayerServerProvider locale={locale}>
    <IntlayerClientProvider locale={locale}>
      {/* Twoje komponenty tutaj */}
    </IntlayerClientProvider>
  </IntlayerServerProvider>
);

Częste błędy i rozwiązywanie problemów

t zwraca undefined lub niepoprawne tłumaczenie

• Przyczyna: Bieżący locale nie jest poprawnie ustawiony lub brakuje tłumaczenia dla bieżącego locale.
• Rozwiązanie:
  • Sprawdź, czy IntlayerClientProvider lub IntlayerServerProvider jest poprawnie skonfigurowany z odpowiednim locale.
• Upewnij się, że obiekt tłumaczeń zawiera wszystkie niezbędne locale.

Brakujące tłumaczenia w TypeScript

• Przyczyna: Obiekt tłumaczeń nie spełnia wymagań dotyczących wszystkich locale, co prowadzi do błędów TypeScript.
• Rozwiązanie: Użyj typu IConfigLocales, aby wymusić kompletność tłumaczeń.

const translations: IConfigLocales<string> = {
  en: "Text",
  fr: "Texte",
  // es: 'Texto', // Brak 'es' spowoduje błąd TypeScript [!code error]
};

const text = t(translations);

Wskazówki dotyczące efektywnego użycia

1. Używaj t do prostych tłumaczeń inline: Idealne do tłumaczenia krótkich fragmentów tekstu bezpośrednio w komponentach.
2. Preferuj useIntlayer do strukturalnej zawartości: Do bardziej złożonych tłumaczeń i ponownego wykorzystania treści definiuj zawartość w plikach deklaracji i używaj useIntlayer.
3. Zapewnij spójne dostarczanie locale: Upewnij się, że locale jest konsekwentnie dostarczane w całej aplikacji za pomocą odpowiednich providerów.
4. Wykorzystaj TypeScript: Używaj typów TypeScript, aby wychwycić brakujące tłumaczenia i zapewnić bezpieczeństwo typów.

Podsumowanie

Funkcja t w next-intlayer to potężne i wygodne narzędzie do zarządzania tłumaczeniami inline w aplikacjach Next.js. Poprzez efektywną integrację zwiększasz możliwości internacjonalizacji swojej aplikacji, zapewniając lepsze doświadczenia użytkownikom na całym świecie.

Aby uzyskać bardziej szczegółowe informacje o użytkowaniu i zaawansowanych funkcjach, zapoznaj się z dokumentacją next-intlayer.

Uwaga: Pamiętaj, aby poprawnie skonfigurować IntlayerClientProvider oraz IntlayerServerProvider, aby bieżące locale było prawidłowo przekazywane do Twoich komponentów. Jest to kluczowe, aby funkcja t zwracała poprawne tłumaczenia.