@intlayer/docs 5.5.10 → 5.5.11

package/frequent_questions/ru/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Команда Intlayer не определена
+description: Узнайте, как исправить ошибку "intlayer command undefined".
+keywords:
+  - intlayer
+  - команда
+  - не определена
+  - ошибка
+  - vscode
+  - расширение
+  - плагин
+  - фреймворк
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - intlayer-command-undefined
+---
+
+# Команда Intlayer не определена
+
+## Обзор
+
+Интерфейс командной строки Intlayer предоставляет удобный способ управления вашим контентом intlayer, включая создание словарей, загрузку переводов и многое другое. Однако он не является обязательным для работы вашего проекта. Если вы используете плагин для сборщика (например, `withIntlayer()` для Next.js или `intlayerPlugin()` для Vite), Intlayer автоматически создаст словари во время сборки приложения или запуска сервера разработки. В режиме разработки он также будет отслеживать изменения и автоматически перестраивать файлы деклараций контента.
+
+Вы можете получить доступ к командам intlayer разными способами:
+
+- Используя команду CLI `intlayer` напрямую
+- Используя [расширение VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/vs_code_extension.md)
+- Используя SDK `@intlayer/cli`
+
+## Проблема
+
+При попытке использовать команду `intlayer` вы можете столкнуться с этой ошибкой:
+
+```bash
+'intlayer' не распознана как внутренняя или внешняя команда,
+исполняемая программа или пакетный файл.
+```
+
+## Решения
+
+Попробуйте следующие решения по порядку:
+
+1. **Проверьте, что команда установлена**
+
+```bash
+npx intlayer -h
+```
+
+Ожидаемый вывод:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            вывод версии
+    -h, --help               показать справку по команде
+
+Commands:
+    dictionary|dictionaries  операции со словарями
+    configuration|config     операции с конфигурацией
+    help [command]           показать справку по команде
+```
+
+2. **Установите пакет intlayer-cli глобально**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Это не должно быть необходимо, если вы уже установили пакет `intlayer`
+
+3. **Установите пакет глобально**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Перезапустите терминал**
+   Иногда для распознавания новых команд требуется перезапуск терминала.
+
+5. **Очистите и переустановите**
+   Если предыдущие решения не помогли:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Проверьте файлы установки**
+   Если проблема сохраняется, убедитесь, что существуют следующие файлы:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (должно содержать поле `bin`, ссылающееся на `./dist/cjs/cli.cjs`)
+
+7. **Проверьте переменную окружения PATH**
+   Убедитесь, что глобальный каталог npm bin включён в ваш PATH:
+
+```bash
+# Для систем на базе Unix (macOS/Linux)
+echo $PATH
+# Должно включать что-то вроде /usr/local/bin или ~/.npm-global/bin
+
+# Для Windows
+echo %PATH%
+# Должно включать каталог глобальных бинарных файлов npm
+```
+
+8. **Используйте npx с полным путем**
+   Если команда по-прежнему не найдена, попробуйте использовать npx с полным путем:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Проверьте наличие конфликтующих установок**
+
+```bash
+# Вывести список всех глобально установленных пакетов
+npm list -g --depth=0
+
+# Удалить любые конфликтующие глобальные установки
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Затем переустановить
+npm install -g intlayer
+```
+
+10. **Проверьте версии Node.js и npm**
+    Убедитесь, что используете совместимые версии:
+
+```bash
+node --version
+npm --version
+```
+
+    Если у вас устаревшая версия, рассмотрите возможность обновления Node.js и npm.
+
+11. **Проверьте проблемы с правами доступа**
+    Если вы получаете ошибки, связанные с правами доступа:
+
+    ```bash
+    # Для систем на базе Unix
+    sudo npm install -g intlayer
+
+    # Или измените каталог по умолчанию для npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Добавьте в ваш ~/.profile или ~/.bashrc:
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/ru/locale_incorect_in_url.md

@@ -0,0 +1,74 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Неверная локаль, полученная из URL
+description: Узнайте, как исправить неверную локаль, полученную из URL.
+keywords:
+  - локаль
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - фреймворк
+  - middleware
+  - конфигурация
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-incorect-in-url
+---
+
+# Неверная локаль, полученная из URL
+
+## Описание проблемы
+
+При попытке получить параметр локали из URL вы можете столкнуться с проблемой, когда значение локали неверно:
+
+```js
+const { locale } = await params;
+console.log(locale); // возвращает "about" вместо ожидаемой локали
+```
+
+## Решение
+
+### 1. Проверьте структуру файлов
+
+Убедитесь, что путь маршрутизатора вашего приложения Next.js соответствует следующей структуре:
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Проверьте конфигурацию Middleware
+
+Проблема часто возникает, когда middleware отсутствует или не срабатывает. Файл middleware должен находиться по адресу:
+
+```bash
+src/middleware.ts
+```
+
+Этот middleware отвечает за переписывание маршрутов, когда `prefixDefault` установлен в `false`. Например, он переписывает `/en/about` в `/about`.
+
+### 3. Шаблоны URL в зависимости от конфигурации
+
+#### Конфигурация по умолчанию (`prefixDefault: false`, `noPrefix: false`)
+
+- Английский: `/about`
+- Французский: `/fr/about`
+- Испанский: `/es/about`
+
+#### При `prefixDefault: true`
+
+- Английский: `/en/about`
+- Французский: `/fr/about`
+- Испанский: `/es/about`
+
+#### При `noPrefix: true`
+
+- Английский: `/about`
+- Французский: `/about`
+- Испанский: `/about`
+
+Для получения дополнительной информации об этих параметрах конфигурации смотрите [Документацию по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).

package/frequent_questions/ru/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Статическая и динамическая отрисовка с i18n в Next.js
+description: Узнайте, как использовать статическую и динамическую отрисовку с i18n в Next.js.
+keywords:
+  - статическая
+  - динамическая
+  - отрисовка
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - фреймворк
+  - middleware
+  - конфигурация
+slugs:
+  - doc
+  - faq
+  - static-rendering
+---
+
+# Статическая и динамическая отрисовка с i18n в Next.js
+
+## Проблема с **next-intl**
+
+- **Что происходит?**
+  Когда вы используете `useTranslations`, `getTranslations` или любой помощник next-intl _внутри серверного компонента_ в приложении с i18n-маршрутизацией (`/en/…`, `/fr/…`), Next.js помечает весь маршрут как **динамический**. ([Next Intl][1])
+
+- **Почему?**
+  next-intl получает текущую локаль из заголовка, доступного только в запросе (`x-next-intl-locale`) через `headers()`. Поскольку `headers()` — это **динамический API**, любой компонент, который его использует, теряет статическую оптимизацию. ([Next Intl][1], [Next.js][2])
+
+- **Официальное решение (шаблон)**
+
+  1. Экспортируйте `generateStaticParams` для каждой поддерживаемой локали.
+  2. Вызывайте `setRequestLocale(locale)` в **каждом** layout/странице _до_ вызова `useTranslations`. ([Next Intl][1])
+     Это устраняет зависимость от заголовка, но теперь у вас появляется дополнительный код для поддержки и нестабильный API в продакшене.
+
+## Как **intlayer** обходит эту проблему
+
+**Выбор архитектуры**
+
+1. **Только параметр маршрута** – Локаль берется из сегмента URL `[locale]`, который Next.js уже передает каждой странице.
+2. **Пакеты на этапе компиляции** – Переводы импортируются как обычные ES-модули, поэтому они подвергаются tree-shaking и встраиваются на этапе сборки.
+3. **Отсутствие динамических API** – `useT()` читает данные из контекста React, а не из `headers()` или `cookies()`.
+4. **Никакой дополнительной настройки** – Как только ваши страницы находятся в папке `app/[locale]/`, Next.js автоматически предварительно рендерит один HTML-файл для каждой локали.

package/frequent_questions/ru/translated_path_url.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Можно ли перевести путь URL?
+description: Узнайте, как перевести путь URL.
+keywords:
+  - массив
+  - контент
+  - объявление
+  - intlayer
+  - промежуточное ПО
+  - прокси
+  - переписывание
+  - префикс
+  - локаль
+  - url
+slugs:
+  - doc
+  - faq
+  - translated-path-url
+---
+
+# Можно ли перевести URL следующим образом:
+
+```bash
+en -> /product (без префикса) или /en/product (с префиксом)
+fr -> /fr/produit
+es -> /es/producto
+```
+
+К сожалению, Intlayer не позволяет переводить URL, как указано выше. Чтобы добиться этого, вам следует использовать собственное промежуточное ПО или прокси для переписывания URL.
+
+Но вы можете использовать функцию `getMultilingualUrl`, чтобы вставить префикс в URL для заданной локали.
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product (без префикса) или /en/product (с префиксом)
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+Или `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // /fr/product
+```

package/frequent_questions/ru/unknown_command.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Неизвестная команда
+description: Узнайте, как исправить ошибку неизвестной команды.
+keywords:
+  - неизвестная
+  - команда
+  - ошибка
+  - intlayer
+  - fill
+  - build
+  - verbose
+  - терминал
+  - перезапуск
+  - локально
+slugs:
+  - doc
+  - faq
+  - unknown-command
+---
+
+# ошибка: неизвестная команда fill / build / и т.д.
+
+Если при выполнении `npx intlayer fill --verbose` появляется:
+
+```
+error: unknown command 'fill'
+```
+
+но вы уверены, что команда `fill` _должна_ существовать, выполните следующие шаги для решения проблемы:
+
+## 1. **Убедитесь, что используете последнюю версию**
+
+Выполните:
+
+```bash
+npx intlayer --version                  # текущая локальная версия intlayer
+npx intlayer@latest --version           # текущая последняя версия intlayer
+```
+
+Это заставит `npx` загрузить самую свежую версию. Затем попробуйте снова:
+
+```bash
+npx intlayer@latest build --verbose
+```
+
+## 2. **Проверьте, зарегистрирована ли команда**
+
+Вы можете проверить с помощью:
+
+```bash
+npx intlayer --help                     # выводит информацию о командах
+```
+
+Посмотрите, появляется ли команда в списке команд.
+
+Перейдите в репозиторий и убедитесь, что ваша команда экспортируется и зарегистрирована в точке входа CLI. Intlayer использует `commander` в качестве фреймворка.
+
+Код, связанный с CLI:
+https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/cli/src/cli.ts
+
+## 4. **Перезапустите терминал**
+
+Иногда для распознавания новых команд требуется перезапуск терминала.
+
+## 5. **Если вы разрабатываете `intlayer`, пересоберите и свяжите его**
+
+Если вы разрабатываете `intlayer` локально:
+
+```bash
+# В директории intlayer
+npm install
+npm run build
+npm link
+```
+
+Тогда в другом терминале:
+
+```bash
+intlayer fill --verbose
+```
+
+Это использует локальную версию, над которой вы работаете.
+
+## 6. **Очистите кэш npx (если вы застряли на старой версии)**
+
+```bash
+npx clear-npx-cache
+```
+
+Или вручную удалите кэшированные пакеты intlayer:
+
+```bash
+rm -rf ~/.npm/_npx
+```
+
+Проверьте эквивалентные команды, если вы используете pnpm, yarn, bun или другой менеджер пакетов

package/frequent_questions/zh/SSR_Next_no_[locale].md

@@ -0,0 +1,105 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: 是否可以在页面路径中不使用 `[locale]` 来搭配 Next.js 使用 Intlayer？
+description: 了解如何在页面路径中不使用 `[locale]` 来搭配 Next.js 使用 Intlayer。
+keywords:
+  - locale
+  - path
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - ssr-next-no-[locale]
+---
+
+# 是否可以在页面路径中不使用 `[locale]` 来搭配 Next.js 使用 Intlayer？
+
+是的，可以在页面路径中不使用 `[locale]` 来搭配 Next.js 使用 Intlayer。然而，不推荐这样做，因为拆分页面路径可以触发更多搜索引擎关键词。您的 SSR 也可能会受到影响。
+
+如果您想这样做，请按照[Intlayer 与 Next.js](https://intlayer.org/doc/environment/nextjs)指南中描述的相同步骤操作，
+
+- 不要使用 `src/middleware.ts`
+- 不要使用 `generateStaticParams`
+
+```tsx fileName="src/app/layout.tsx"
+import type { FC, PropsWithChildren } from "react";
+
+const LocaleLayout: FC<PropsWithChildren> = ({ children }) => (
+  <html lang={undefined} dir={undefined}>
+    <body className={inter.className}>{children}</body>
+  </html>
+);
+
+export default LocaleLayout;
+```
+
+```tsx fileName="src/app/page.tsx"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { PageContent } from "@components/pageContent";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC = () => {
+  return (
+    <IntlayerServerProvider>
+      <PageContent />
+      <ServerComponentExample />
+
+      <IntlayerClientProvider>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```tsx fileName="src/component/pageContent.ts"
+"use client";
+
+import { type FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { useHTMLLanguage } from "@hooks/htmlTextDir";
+
+const PageContent: FC = () => {
+  useHTMLLanguage();
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/hooks/htmlTextDir.ts"
+"use client";
+
+import { useEffect } from "react";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const useHTMLLanguage = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    if (!document) return;
+
+    document.documentElement.lang = locale; // 设置HTML文档的语言属性
+    document.documentElement.dir = getHTMLTextDir(locale); // 设置文本方向属性（ltr或rtl）
+  }, [locale]);
+};
+```

package/frequent_questions/zh/array_as_content_declaration.md

@@ -0,0 +1,72 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: 我可以使用数组作为内容声明吗？
+description: 了解如何使用数组作为内容声明。
+keywords:
+  - 数组
+  - 内容
+  - 声明
+  - intlayer
+slugs:
+  - doc
+  - faq
+  - array-as-content-declaration
+---
+
+# 我可以使用数组作为内容声明吗？
+
+是的，您可以使用数组作为内容声明。
+
+```ts
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  content: {
+    test: t({
+      en: ["Test", "Test2", "Test3"],
+      fr: ["Test", "Test2", "Test3"],
+      es: ["Test", "Test2", "Test3"],
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+然后您可以这样使用内容：
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+
+const Example = () => {
+  const content = useIntlayer("example");
+
+  return (
+    <div>
+      {content.test.map((item) => (
+        <div key={item.value}>{item}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+```vue
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("example");
+</script>
+
+<template>
+  <div>
+    <div v-for="item in content.test" :key="item.value">
+      {{ item }}
+    </div>
+  </div>
+</template>
+```
+
+`.value` 允许您获取内容的值，而不是被 `IntlayerNode` 包装的内容。

package/frequent_questions/zh/build_dictionaries.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: 如何构建字典？
+description: 学习如何构建字典。
+keywords:
+  - 构建
+  - 字典
+  - intlayer
+  - 命令
+  - 监听
+  - vscode
+  - 插件
+  - 框架
+  - next.js
+  - vite
+slugs:
+  - 文档
+  - 常见问题
+  - 构建字典
+---
+
+# 构建字典
+
+## 如何构建字典
+
+Intlayer 提供了一个命令行工具来构建字典。
+
+```bash
+npx intlayer dictionaries build
+```
+
+该命令：
+
+- 扫描项目中所有内容声明文件（`.content.{ts,tsx,js,mjs,cjs,json,...}`）。
+- 生成字典并将其存储在 `.intlayer/dictionary` 文件夹中。
+
+### 监听模式
+
+如果您希望在内容声明文件发生更改时自动更新字典，请运行以下命令：
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+在此模式下，Intlayer 会在内容声明文件发生更改时扫描并构建字典，并自动更新 `.intlayer/dictionary` 文件夹。
+
+### 使用 VSCode 扩展
+
+您还可以使用[Intlayer VSCode 扩展](https://github.com/aymericzip/intlayer/tree/main/docs/zh/vs_code_extension.md)来增强您在 VSCode 中的 Intlayer 体验。
+
+### 使用您喜欢的应用框架插件
+
+如果您使用的是像 Next.js（Webpack / Turbopack）、Vite、React Native、Lynx 等框架，Intlayer 提供了一个插件，您可以使用该插件将 Intlayer 集成到您的应用程序中。
+
+Intlayer 会在您的应用程序构建之前构建字典。
+同样，在开发模式下，Intlayer 会监视内容声明文件的更改并自动重新构建字典。
+
+因此，请参考您所使用框架的具体文档，了解如何集成该插件。