Next.js Интеграция: Документация по хуку useIntlayerAsync

Хук useIntlayerAsync расширяет функциональность useIntlayer, возвращая не только предварительно отрендеренные словари, но и асинхронно извлекая обновления, что делает его идеальным для приложений, которые часто обновляют свой локализованный контент после первоначального рендера.

Обзор

• Асинхронная загрузка словарей:
  На стороне клиента useIntlayerAsync сначала возвращает предварительно отрендеренный словарь локали (точно так же, как useIntlayer), а затем асинхронно извлекает и объединяет любые новые доступные удаленные словари.
• Управление состоянием загрузки:
  Хук также предоставляет состояние isLoading, указывающее, когда загружается удаленный словарь. Это позволяет разработчикам отображать индикаторы загрузки или состояния скелета для более плавного взаимодействия с пользователем.

Настройка окружения

Intlayer предоставляет безголовую систему управления контентом (CSM), позволяющую неразработчикам управлять и обновлять контент приложения без швов. Используя интуитивно понятную панель управления Intlayer, ваша команда может редактировать локализованный текст, изображения и другие ресурсы, не изменяя напрямую код. Это упрощает процесс управления контентом, способствует сотрудничеству и обеспечивает быстрое и легкое внесение обновлений.

Чтобы начать работу с Intlayer, вам сначала нужно зарегистрироваться и получить токен доступа на /ru/dashboard. Как только у вас будут ваши учетные данные, добавьте их в файл конфигурации, как показано ниже:

import { type IntlayerConfig } from 'intlayer';

export default {
  ...
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
  },
} satisfies IntlayerConfig;

После настройки ваших учетных данных вы можете отправить новый словарь локали в Intlayer, выполнив:

npm intlayer push -d my-first-dictionary-key

Эта команда загружает ваши первоначальные словари контента, делая их доступными для асинхронной обработки и редактирования через платформу Intlayer.

Импортирование useIntlayerAsync в Next.js

Поскольку useIntlayerAsync предназначен для клиентских компонентов, вы будете импортировать его из той же клиентской точки входа, что и useIntlayer:

"use client";

import { useIntlayerAsync } from "next-intlayer";

Убедитесь, что импортируемый файл аннотирован "use client" вверху, если вы используете маршрутизатор приложения Next.js с разделенными серверными и клиентскими компонентами.

Параметры

1. key:
   Тип: DictionaryKeys
   Ключ словаря, используемый для идентификации блока локализованного контента. Этот ключ должен быть определен в ваших файлах декларации контента.

2. locale (необязательно):
   Тип: Locales
   Конкретная локаль, которую вы хотите нацелить. Если упущено, хук использует локаль из контекста клиента.

3. isRenderEditor (необязательно, по умолчанию true):
   Тип: boolean
   Определяет, следует ли готовить контент к рендерингу с наложением редактора Intlayer. Если установлен в false, возвращенные данные словаря будут исключать редакторские функции.

Значение возврата

Хук возвращает объект словаря с локализованным контентом, ключевым по key и locale. Он также включает булеву переменную isLoading, указывающую, загружается ли в данный момент удаленный словарь.

Пример использования в Next.js

Пример клиентского компонента

"use client";

import { useEffect } from "react";
import { useIntlayerAsync } from "next-intlayer";

export const AsyncClientComponentExample = () => {
  const { title, description, isLoading } = useIntlayerAsync("async-component");

  useEffect(() => {
    if (isLoading) {
      console.log("Контент загружается...");
    }
  }, [isLoading]);

  return (
    <div>
      <h1>{title.value}</h1>
      <p>{description.value}</p>
    </div>
  );
};

Ключевые моменты:

• При первоначальном рендере title и description берутся из предварительно отрендеренного словаря локали.
• Когда isLoading true, в фоне производится удаленный запрос на получение обновленного словаря.
• После завершения извлечения title и description обновляются с новым контентом, и isLoading возвращается к false.

Обработка локализации атрибутов

Как и с useIntlayer, вы можете извлекать локализованные значения атрибутов для различных свойств HTML (например, alt, title, aria-label):

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

Файлы декларации контента

Все ключи контента должны быть определены в ваших файлах декларации контента для обеспечения типобезопасности и предотвращения ошибок выполнения. Эти файлы обеспечивают валидацию TypeScript, гарантируя, что вы всегда обращаетесь к существующим ключам и локалям.

Инструкции по настройке файлов декларации контента доступны здесь.

Дополнительная информация

• Визуальный редактор Intlayer:
  Интеграция с визуальным редактором Intlayer для управления и редактирования контента прямо из интерфейса. Более подробная информация здесь.

В заключение, useIntlayerAsync — это мощный хук клиентской стороны, предназначенный для улучшения взаимодействия с пользователем и поддержания свежести контента, соединяющий предварительно отрендеренные словари с асинхронными обновлениями словарей. Используя isLoading и декларации контента на основе TypeScript, вы можете бесшовно интегрировать динамический, локализованный контент в ваши приложения Next.js.