Документация: Функция t в next-intlayer

Функция t в пакете next-intlayer является основным инструментом для встроенной интернационализации в вашем приложении Next.js. Она позволяет вам определять переводы прямо внутри ваших компонентов, что облегчает отображение локализованного контента в зависимости от текущей локали.

Обзор

Функция t используется для предоставления переводов для различных локалей напрямую в ваши компоненты. Передавая объект, содержащий переводы для каждой поддерживаемой локали, t возвращает соответствующий перевод в зависимости от контекста текущей локали в вашем приложении Next.js.

Ключевые особенности

• Встроенные переводы: Идеально подходит для быстрого встроенного текста, который не требует отдельного объявления контента.
• Автоматический выбор локали: Автоматически возвращает перевод, соответствующий текущей локали.
• Поддержка TypeScript: Обеспечивает безопасность типов и автозаполнение при использовании с TypeScript.
• Легкая интеграция: Работает без проблем как в клиентских, так и в серверных компонентах Next.js.

Подпись функции

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

Параметры

• translations: Объект, где ключи — это коды локалей (например, en, fr, es), а значения — соответствующие переведенные строки.

Возвращает

• Строку, представляющую переведенный контент для текущей локали.

Примеры использования

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

Убедитесь, что вы включили директиву 'use client'; в верхней части вашего файла компонента при использовании t в компоненте на стороне клиента.

"use client";

import { t } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  return (
    <div>
      <p>
        {t({
          en: "Это содержимое примера клиентского компонента",
          fr: "Ceci est le contenu d'un exemple de composant client",
          es: "Este es el contenido d un ejemplo de componente cliente",
        })}
      </p>
    </div>
  );
};

Использование t в серверном компоненте

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

export const ServerComponentExample = () => {
  return (
    <div>
      <p>
        {t({
          en: "Это содержимое примера серверного компонента",
          fr: "Ceci est le contenu d'un exemple de composant serveur",
          es: "Este es el contenido de un ejemplo de componente servidor",
        })}
      </p>
    </div>
  );
};

Встроенные переводы в атрибутах

Функция t особенно полезна для встроенных переводов в атрибутах JSX. Когда вы локализуете атрибуты, такие как alt, title, href или aria-label, вы можете использовать t непосредственно внутри атрибута.

<button
  aria-label={t({
    en: "Отправить",
    fr: "Soumettre",
    es: "Enviar",
  })}
>
  {t({
    en: "Отправить",
    fr: "Soumettre",
    es: "Enviar",
  })}
  <img
    src="/path/to/image"
    alt={t({
      en: "Красивая сцена",
      fr: "Un beau paysage",
      es: "Un hermoso paisaje",
    })}
  />
</button>

Продвинутые темы

Интеграция TypeScript

Функция t безопасна по типам, когда используется с TypeScript, что обеспечивает предоставление всех необходимых локалей.

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

const translations: IConfigLocales<string> = {
  en: "Добро пожаловать",
  fr: "Bienvenue",
  es: "Bienvenido",
};

const greeting = t(translations);

Обнаружение локали и контекст

В next-intlayer текущая локаль управляется через провайдеры контекста: IntlayerClientProvider и IntlayerServerProvider. Убедитесь, что эти провайдеры оборачивают ваши компоненты, а пропс locale правильно передан.

Пример:

import { IntlayerClientProvider } from "next-intlayer";

const Page = ({ locale }) => (
  <IntlayerServerProvider locale={locale}>
    <IntlayerClientProvider locale={locale}>
      {/* Ваши компоненты здесь */}
    </IntlayerClientProvider>
  </IntlayerServerProvider>
);

Общие ошибки и устранение неполадок

t возвращает неопределенное или неправильное значение перевода

• Причина: Текущая локаль неправильно установлена или перевод для текущей локали отсутствует.
• Решение:
  • Проверьте, что IntlayerClientProvider или IntlayerServerProvider правильно настроены с соответствующей локалью.
  • Убедитесь, что ваш объект переводов включает все необходимые локали.

Отсутствующие переводы в TypeScript

• Причина: Объект переводов не удовлетворяет требованиям по локалям, что приводит к ошибкам TypeScript.
• Решение: Используйте тип IConfigLocales, чтобы обеспечить полноту ваших переводов.

const translations: IConfigLocales<string> = {
  en: "Текст",
  fr: "Texte",
  // es: 'Texto', // Отсутствие 'es' приведет к ошибке TypeScript
};

const text = t(translations);

Советы для эффективного использования

1. Используйте t для простых встроенных переводов: Идеально подходит для перевода небольших частей текста прямо внутри ваших компонентов.
2. Предпочитайте useIntlayer для структурированного контента: Для более сложных переводов и повторного использования контента определяйте контент в файлах декларации и используйте useIntlayer.
3. Постоянное предоставление локали: Убедитесь, что ваша локаль последовательно предоставляется по всему вашему приложению через соответствующие провайдеры.
4. Используйте TypeScript: Используйте типы TypeScript, чтобы поймать отсутствующие переводы и обеспечить безопасность типов.

Заключение

Функция t в next-intlayer является мощным и удобным инструментом для управления встроенными переводами в ваших приложениях Next.js. Эффективная интеграция её улучшает возможности интернационализации вашего приложения, обеспечивая лучший опыт для пользователей по всему миру.

Для более подробного использования и расширенных функций обратитесь к документации next-intlayer.

Примечание: Не забудьте правильно настроить ваши IntlayerClientProvider и IntlayerServerProvider, чтобы гарантировать правильную передачу текущей локали вашим компонентам. Это критично для корректного возвращения переводов функцией t.