@intlayer/docs 5.8.1-canary.0 → 6.0.0-canary.0

package/docs/pt/testing.md

@@ -0,0 +1,200 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: Testando seu conteúdo
+description: Descubra como testar seu conteúdo com Intlayer.
+keywords:
+  - Testes
+  - Intlayer
+  - Internacionalização
+  - CMS
+  - Sistema de Gestão de Conteúdo
+  - Editor Visual
+slugs:
+  - doc
+  - testing
+---
+
+# Testando seu conteúdo
+
+Este guia mostra como verificar automaticamente se seus dicionários estão completos, detectar traduções faltantes antes do lançamento e testar a interface localizada em seu aplicativo.
+
+---
+
+## O que você pode testar
+
+- **Traduções faltantes**: falhar no CI se algum idioma obrigatório estiver faltando em qualquer dicionário.
+- **Renderização da interface localizada**: renderizar componentes com um provedor de idioma específico e verificar textos/atributos visíveis.
+- **Auditorias em tempo de build**: executar uma auditoria rápida localmente via CLI.
+
+---
+
+## Início rápido: auditoria via CLI
+
+Execute a auditoria a partir da raiz do seu projeto:
+
+```bash
+npx intlayer content test
+```
+
+Flags úteis:
+
+- `--env-file [caminho]`: carrega variáveis de ambiente a partir de um arquivo.
+- `-e, --env [nome]`: seleciona um perfil de ambiente.
+- `--base-dir [caminho]`: define o diretório base do app para resolução.
+- `--verbose`: exibe logs detalhados.
+- `--prefix [rótulo]`: prefixa as linhas de log.
+
+Nota: o CLI imprime um relatório detalhado, mas não retorna código de erro em caso de falhas. Para controle em CI, adicione um teste unitário (abaixo) que assegure que não há locais obrigatórios faltando.
+
+---
+
+## Teste programático (Vitest/Jest)
+
+Use a API do CLI do Intlayer para garantir que não há traduções faltando para os locais obrigatórios.
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("traduções", () => {
+  it("não possui locais obrigatórios faltando", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // Útil quando o teste falha localmente ou no CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Equivalente em Jest:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("não possui locais obrigatórios faltando", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+Como funciona:
+
+- O Intlayer lê sua configuração (locales, requiredLocales) e os dicionários declarados, então reporta:
+  - `missingTranslations`: por chave, quais locais estão faltando e de qual arquivo.
+  - `missingLocales`: união de todos os locais faltantes.
+  - `missingRequiredLocales`: subconjunto limitado a `requiredLocales` (ou todos os locais se `requiredLocales` não estiver definido).
+
+---
+
+## Testando UI localizada (React / Next.js)
+
+Renderize componentes dentro de um provedor Intlayer e faça asserções no conteúdo visível.
+
+Exemplo React (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localized title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByText("Título esperado em inglês")).toBeInTheDocument();
+});
+```
+
+Exemplo Next.js (App Router): use o wrapper do framework:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("renderiza título localizado em francês", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+Dicas:
+
+- Quando precisar dos valores brutos das strings para atributos (ex.: `aria-label`), acesse o campo `.value` retornado por `useIntlayer` no React.
+- Mantenha os dicionários localizados junto com os componentes para facilitar os testes unitários e a limpeza.
+
+---
+
+## Integração Contínua
+
+Adicione um teste que falhe a build quando traduções obrigatórias estiverem faltando.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+Exemplo GitHub Actions:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+Opcional: execute a auditoria CLI para um resumo legível por humanos junto com os testes:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## Solução de Problemas
+
+- Certifique-se de que sua configuração do Intlayer define `locales` e (opcionalmente) `requiredLocales`.
+- Se seu aplicativo usa dicionários dinâmicos ou remotos, execute os testes em um ambiente onde os dicionários estejam disponíveis.
+- Para monorepos mistos, use `--base-dir` para apontar o CLI para a raiz correta da aplicação.
+
+---
+
+## Histórico do Documento
+
+| Versão | Data       | Alterações            |
+| ------ | ---------- | --------------------- |
+| 6.0.0  | 2025-09-20 | Introdução dos testes |

package/docs/ru/autoFill.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
+updatedAt: 2025-09-20
 title: Автозаполнение
-description: Узнайте, как использовать функцию автозаполнения в Intlayer для автоматического заполнения контента на основе предопределённых шаблонов. Следуйте этой документации, чтобы эффективно реализовать функции автозаполнения в вашем проекте.
+description: Узнайте, как использовать функцию автозаполнения в Intlayer для автоматического заполнения контента на основе предопределённых шаблонов. Следуйте этой документации, чтобы эффективно внедрить функции автозаполнения в вашем проекте.
 keywords:
   - Автозаполнение
   - Автоматизация контента
@@ -17,28 +17,28 @@ slugs:
   - auto-fill
 ---
 
-# Файлы декларации контента с автозаполнением
+# Переводы файлов декларации автозаполнения контента
 
-**Файлы декларации контента с автозаполнением** - это способ ускорить ваш процесс разработки.
-Механизм автозаполнения работает через отношение _мастер-слейв_ между файлами декларации контента. Когда основной (мастер) файл обновляется, Intlayer автоматически применяет эти изменения к производным (автозаполненным) файлам декларации.
+**Файлы декларации автозаполнения контента** — это способ ускорить ваш процесс разработки.
+
+Механизм автозаполнения работает через _мастер-слейв_ отношения между файлами декларации контента. Когда основной (мастер) файл обновляется, Intlayer автоматически применяет эти изменения к производным (автозаполненным) файлам декларации.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
 
-// Основной файл декларации контента с автозаполнением
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "This is an example of content", // Это пример содержимого
+    contentExample: "Это пример контента", // пример контента
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-Вот [файл декларации контента для каждого языка](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/per_locale_file.md), использующий инструкцию `autoFill`.
+Вот [файл декларации контента для каждого локаля](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/per_locale_file.md), использующий инструкцию `autoFill`.
 
 Затем, когда вы выполните следующую команду:
 
@@ -46,7 +46,7 @@ export default exampleContent;
 npx intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer автоматически сгенерирует производный файл декларации по пути `src/components/example/example.content.json`, заполнив все локали, которые ещё не объявлены в основном файле.
+Intlayer автоматически сгенерирует производный файл декларации по пути `src/components/example/example.content.json`, заполняя все локали, которые ещё не объявлены в основном файле.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -63,23 +63,23 @@ Intlayer автоматически сгенерирует производны
 }
 ```
 
-После этого оба файла декларации будут объединены в один словарь, доступный через стандартный хук `useIntlayer("example")` (react) / композицию (vue).
+После этого оба файла деклараций будут объединены в один словарь, доступный через стандартный хук `useIntlayer("example")` (react) / композицию (vue).
 
-## Формат файла с автозаполнением
+## Формат автозаполненного файла
 
-Рекомендуемый формат для автоматически заполняемых файлов деклараций - **JSON**, что помогает избежать ограничений форматирования. Однако Intlayer также поддерживает форматы `.ts`, `.js`, `.mjs`, `.cjs` и другие.
+Рекомендуемый формат для автоматически заполняемых файлов деклараций — **JSON**, который помогает избежать ограничений форматирования. Однако Intlayer также поддерживает форматы `.ts`, `.js`, `.mjs`, `.cjs` и другие.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
   key: "example",
   autoFill: "./example.filled.content.ts",
   content: {
-    // Ваш контент
+    // Ваше содержимое
   },
 };
 ```
 
-Это создаст файл по пути:
+Это сгенерирует файл по адресу:
 
 ```
 src/components/example/example.filled.content.ts
@@ -87,8 +87,8 @@ src/components/example/example.filled.content.ts
 
 > Генерация файлов `.js`, `.ts` и подобных работает следующим образом:
 >
-> - Если файл уже существует, Intlayer проанализирует его с помощью AST (Абстрактного Синтаксического Дерева), чтобы найти каждое поле и вставить отсутствующие переводы.
-> - Если файл не существует, Intlayer создаст его, используя шаблон файла декларации контента по умолчанию.
+> - Если файл уже существует, Intlayer будет парсить его с помощью AST (Абстрактного синтаксического дерева), чтобы найти каждое поле и вставить отсутствующие переводы.
+> - Если файл не существует, Intlayer сгенерирует его, используя шаблон файла декларации содержимого по умолчанию.
 
 ## Абсолютные пути
 
@@ -99,20 +99,20 @@ const exampleContent = {
   key: "example",
   autoFill: "/messages/example.content.json",
   content: {
-    // Ваш контент
+    // Ваше содержимое
   },
 };
 ```
 
-Это создаст файл по пути:
+Это сгенерирует файл по адресу:
 
 ```
 /messages/example.content.json
 ```
 
-## Автоматическая генерация файлов декларации контента для каждого локаля
+## Автоматическая генерация файлов деклараций содержимого для каждого локаля
 
-Поле `autoFill` также поддерживает генерацию файлов декларации контента **для каждого локаля**.
+Поле `autoFill` также поддерживает генерацию файлов деклараций содержимого **для каждого локаля**.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -122,17 +122,19 @@ const exampleContent = {
     es: "./example.es.content.json",
   },
   content: {
-    // Ваш контент
+    // Ваше содержимое
   },
 };
 ```
 
-Это создаст два отдельных файла:
+Это сгенерирует два отдельных файла:
 
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## Фильтрация автозаполнения по конкретному локалю
+> В этом случае, если объект не содержит все локали, Intlayer пропускает генерацию оставшихся локалей.
+
+## Фильтрация автозаполнения для конкретной локали
 
 Использование объекта в поле `autoFill` позволяет применять фильтры и генерировать файлы только для определённых локалей.
 
@@ -143,37 +145,57 @@ const exampleContent = {
     fr: "./example.fr.content.json",
   },
   content: {
-    // Ваш контент
+    // Ваше содержимое
   },
 };
 ```
 
-Это создаст только файл перевода для французского языка.
+Это сгенерирует только файл перевода на французский язык.
 
 ## Переменные пути
 
-Вы можете использовать переменные внутри пути `autoFill` для динамического определения целевых путей создаваемых файлов.
+ Вы можете использовать переменные внутри пути `autoFill` для динамического определения целевых путей для сгенерированных файлов.
 
 **Доступные переменные:**
 
 - `{{locale}}` – Код локали (например, `fr`, `es`)
+- `{{fileName}}` – Имя файла (например, `index`)
 - `{{key}}` – Ключ словаря (например, `example`)
 
-```ts fileName="src/components/example/example.content.ts"
+```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
   autoFill: "/messages/{{locale}}/{{key}}.content.json",
   content: {
-    // Ваш контент
+    // Ваше содержимое
   },
 };
 ```
 
-Это создаст:
+Это сгенерирует:
 
 - `/messages/fr/example.content.json`
 - `/messages/es/example.content.json`
 
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // Ваше содержимое
+  },
+};
+```
+
+Это сгенерирует:
+
+- `./index.content.json`
+- `./index.content.json`
+
 ## История документации
 
-- 5.5.10 - 2025-06-29: Инициализация истории
+| Версия  | Дата       | Изменения                  |
+| ------- | ---------- | -------------------------- |
+| 6.0.0   | 2025-09-20 | Добавлена глобальная конфигурация |
+| 6.0.0   | 2025-09-17 | Добавлена переменная `{{fileName}}` |
+| 5.5.10  | 2025-06-29 | Инициализация истории      |