@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/ko/testing.md

@@ -0,0 +1,200 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: 콘텐츠 테스트하기
+description: Intlayer로 콘텐츠를 테스트하는 방법을 알아보세요.
+keywords:
+  - 테스트
+  - Intlayer
+  - 국제화
+  - CMS
+  - 콘텐츠 관리 시스템
+  - 비주얼 에디터
+slugs:
+  - doc
+  - testing
+---
+
+# 콘텐츠 테스트하기
+
+이 가이드는 사전이 완전한지 자동으로 확인하고, 배포 전에 누락된 번역을 잡아내며, 앱에서 현지화된 UI를 테스트하는 방법을 보여줍니다.
+
+---
+
+## 테스트할 수 있는 항목
+
+- **누락된 번역**: 필수 로케일이 사전에서 누락된 경우 CI 실패 처리.
+- **현지화된 UI 렌더링**: 특정 로케일 제공자와 함께 컴포넌트를 렌더링하고, 표시된 텍스트/속성을 검증.
+- **빌드 시 감사**: CLI를 통해 로컬에서 빠른 감사를 실행.
+
+---
+
+## 빠른 시작: CLI를 통한 감사
+
+프로젝트 루트에서 감사를 실행하세요:
+
+```bash
+npx intlayer content test
+```
+
+유용한 플래그:
+
+- `--env-file [path]`: 파일에서 환경 변수를 로드합니다.
+- `-e, --env [name]`: 환경 프로필을 선택합니다.
+- `--base-dir [path]`: 해석을 위한 앱 기본 디렉터리를 설정합니다.
+- `--verbose`: 자세한 로그를 표시합니다.
+- `--prefix [label]`: 로그 라인에 접두사를 붙입니다.
+
+참고: CLI는 상세 보고서를 출력하지만 실패 시 비영(0이 아닌) 종료 코드를 반환하지 않습니다. CI 게이팅을 위해, 아래 단위 테스트를 추가하여 필수 로케일 누락이 0임을 확인하세요.
+
+---
+
+## 프로그래밍 방식 테스트 (Vitest/Jest)
+
+Intlayer CLI API를 사용하여 필수 로케일에 누락된 번역이 없는지 확인하세요.
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("번역", () => {
+  it("필수 로케일이 누락되지 않음", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // 테스트가 로컬 또는 CI에서 실패할 때 도움이 됨
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Jest 동등 코드:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("필수 로케일이 누락되지 않음", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+작동 방식:
+
+- Intlayer는 구성(locales, requiredLocales)과 선언된 사전을 읽고 다음을 보고합니다:
+  - `missingTranslations`: 키별로 어떤 로케일이 누락되었고 어떤 파일에서 누락되었는지.
+  - `missingLocales`: 누락된 모든 로케일의 합집합.
+  - `missingRequiredLocales`: `requiredLocales`로 제한된 부분집합 (또는 `requiredLocales`가 설정되지 않은 경우 모든 로케일).
+
+---
+
+## 지역화된 UI 테스트 (React / Next.js)
+
+Intlayer 프로바이더 하에 컴포넌트를 렌더링하고 화면에 보이는 내용을 검증합니다.
+
+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("Expected English title")).toBeInTheDocument();
+});
+```
+
+Next.js (앱 라우터) 예제: 프레임워크 래퍼 사용:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("프랑스어로 현지화된 제목을 렌더링합니다", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+팁:
+
+- 속성(예: `aria-label`)에 대한 원시 문자열 값이 필요할 때는 React에서 `useIntlayer`가 반환하는 `.value` 필드에 접근하세요.
+- 단위 테스트 및 정리를 쉽게 하기 위해 사전을 컴포넌트와 함께 배치하세요.
+
+---
+
+## 지속적 통합
+
+필수 번역이 누락되었을 때 빌드를 실패하게 하는 테스트를 추가하세요.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+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
+```
+
+선택 사항: 테스트와 함께 사람이 읽기 쉬운 요약을 위해 CLI 감사를 실행하세요:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## 문제 해결
+
+- Intlayer 구성에 `locales` 및 (선택적으로) `requiredLocales`가 정의되어 있는지 확인하세요.
+- 앱이 동적 또는 원격 사전을 사용하는 경우, 사전이 사용 가능한 환경에서 테스트를 실행하세요.
+- 혼합 모노레포의 경우, CLI가 올바른 애플리케이션 루트를 가리키도록 `--base-dir`을 사용하세요.
+
+---
+
+## 문서 이력
+
+| 버전  | 날짜       | 변경 사항   |
+| ----- | ---------- | ----------- |
+| 6.0.0 | 2025-09-20 | 테스트 도입 |

package/docs/pt/autoFill.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
+updatedAt: 2025-09-20
 title: Preenchimento Automático
-description: Aprenda como usar a funcionalidade de preenchimento automático no Intlayer para popular conteúdo automaticamente com base em padrões predefinidos. Siga esta documentação para implementar recursos de preenchimento automático de forma eficiente em seu projeto.
+description: Aprenda a usar a funcionalidade de preenchimento automático no Intlayer para popular conteúdo automaticamente com base em padrões predefinidos. Siga esta documentação para implementar recursos de preenchimento automático de forma eficiente em seu projeto.
 keywords:
   - Preenchimento Automático
   - Automação de Conteúdo
@@ -20,6 +20,7 @@ slugs:
 # Traduções de Arquivos de Declaração de Conteúdo com Preenchimento Automático
 
 **Arquivos de declaração de conteúdo com preenchimento automático** são uma forma de acelerar seu fluxo de trabalho de desenvolvimento.
+
 O mecanismo de preenchimento automático funciona através de uma relação _mestre-escravo_ entre arquivos de declaração de conteúdo. Quando o arquivo principal (mestre) é atualizado, o Intlayer aplicará automaticamente essas alterações aos arquivos de declaração derivados (preenchidos automaticamente).
 
 ```ts fileName="src/components/example/example.content.ts"
@@ -30,10 +31,11 @@ const exampleContent = {
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "Este é um exemplo de conteúdo", // comentário em português
+    contentExample: "Este é um exemplo de conteúdo",
   },
 } satisfies Dictionary;
 
+// Exporta o conteúdo de exemplo
 export default exampleContent;
 ```
 
@@ -45,7 +47,7 @@ Então, quando você executar o seguinte comando:
 npx intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-O Intlayer gerará automaticamente o arquivo de declaração derivado em `src/components/example/example.content.json`, preenchendo todos os locais que ainda não foram declarados no arquivo principal.
+O Intlayer irá gerar automaticamente o arquivo de declaração derivado em `src/components/example/example.content.json`, preenchendo todos os locais que ainda não foram declarados no arquivo principal.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -62,11 +64,11 @@ O Intlayer gerará automaticamente o arquivo de declaração derivado em `src/co
 }
 ```
 
-Depois disso, ambos os arquivos de declaração serão mesclados em um único dicionário, acessível usando o hook padrão `useIntlayer("example")` (react) / composable (vue).
+Posteriormente, ambos os arquivos de declaração serão mesclados em um único dicionário, acessível usando o hook padrão `useIntlayer("example")` (react) / composable (vue).
 
 ## Formato do Arquivo Preenchido Automaticamente
 
-O formato recomendado para arquivos de declaração preenchidos automaticamente é **JSON**, o que ajuda a evitar restrições de formatação. No entanto, o Intlayer também suporta os formatos `.ts`, `.js`, `.mjs`, `.cjs` e outros.
+O formato recomendado para arquivos de declaração preenchidos automaticamente é **JSON**, que ajuda a evitar restrições de formatação. No entanto, o Intlayer também suporta `.ts`, `.js`, `.mjs`, `.cjs` e outros formatos.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -78,7 +80,7 @@ const exampleContent = {
 };
 ```
 
-Isso gerará o arquivo em:
+Isso irá gerar o arquivo em:
 
 ```
 src/components/example/example.filled.content.ts
@@ -86,7 +88,7 @@ src/components/example/example.filled.content.ts
 
 > A geração de arquivos `.js`, `.ts` e similares funciona da seguinte forma:
 >
-> - Se o arquivo já existir, o Intlayer irá analisá-lo usando AST (Abstract Syntax Tree) para localizar cada campo e inserir quaisquer traduções faltantes.
+> - Se o arquivo já existir, o Intlayer irá analisá-lo usando AST (Árvore de Sintaxe Abstrata) para localizar cada campo e inserir quaisquer traduções faltantes.
 > - Se o arquivo não existir, o Intlayer irá gerá-lo usando o template padrão de arquivo de declaração de conteúdo.
 
 ## Caminhos Absolutos
@@ -109,7 +111,7 @@ Isso irá gerar o arquivo em:
 /messages/example.content.json
 ```
 
-## Autogerar Arquivos de Declaração de Conteúdo Por Localidade
+## Geração Automática de Arquivos de Declaração de Conteúdo Por Localidade
 
 O campo `autoFill` também suporta a geração de arquivos de declaração de conteúdo **por localidade**.
 
@@ -131,9 +133,11 @@ Isso irá gerar dois arquivos separados:
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## Filtrar AutoPreenchimento por Locale Específico
+> Neste caso, se o objeto não contiver todas as localidades, o Intlayer pula a geração das localidades restantes.
 
-Usar um objeto para o campo `autoFill` permite aplicar filtros e gerar apenas arquivos de locale específicos.
+## Filtrar Autofill para Localidade Específica
+
+Usar um objeto para o campo `autoFill` permite aplicar filtros e gerar apenas arquivos de localidades específicas.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -155,10 +159,11 @@ Você pode usar variáveis dentro do caminho `autoFill` para resolver dinamicame
 
 **Variáveis disponíveis:**
 
-- `{{locale}}` – Código do locale (ex.: `fr`, `es`)
+- `{{locale}}` – Código da localidade (ex.: `fr`, `es`)
+- `{{fileName}}` – Nome do arquivo (ex.: `index`)
 - `{{key}}` – Chave do dicionário (ex.: `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",
@@ -173,6 +178,25 @@ Isso irá gerar:
 - `/messages/fr/example.content.json`
 - `/messages/es/example.content.json`
 
-## Histórico da Documentação
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso irá gerar:
+
+- `./index.content.json`
+- `./index.content.json`
+
+## Histórico do Documento
 
-- 5.5.10 - 2025-06-29: Histórico inicial
+| Versão  | Data       | Alterações                  |
+| ------- | ---------- | --------------------------- |
+| 6.0.0   | 2025-09-20 | Adicionada configuração global |
+| 6.0.0   | 2025-09-17 | Adicionada variável `{{fileName}}` |
+| 5.5.10  | 2025-06-29 | Histórico inicial           |