@intlayer/docs 5.5.8

package/ko/vs_code_extension.md

@@ -0,0 +1,139 @@
+# 공식 VS Code 확장 프로그램
+
+## 개요
+
+**Intlayer**는 **Intlayer**의 공식 Visual Studio Code 확장 프로그램으로, **React, Next.js, JavaScript** 프로젝트에서 로컬라이즈된 콘텐츠 작업 시 개발자 경험을 향상시키기 위해 설계되었습니다.
+
+이 확장 프로그램을 사용하면 개발자는 콘텐츠 사전을 **빠르게 탐색**하고, 로컬라이제이션 파일을 관리하며, 강력한 자동화 명령으로 워크플로우를 간소화할 수 있습니다.
+
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+
+확장 프로그램 링크: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
+
+## 기능
+
+### 즉시 탐색
+
+**정의로 이동 지원** – `useIntlayer` 키를 `Cmd+Click` (Mac) 또는 `Ctrl+Click` (Windows/Linux)으로 클릭하여 해당 콘텐츠 파일을 즉시 엽니다.  
+**원활한 통합** – **react-intlayer** 및 **next-intlayer** 프로젝트와 매끄럽게 작동합니다.  
+**다국어 지원** – 다양한 언어의 로컬라이즈된 콘텐츠를 지원합니다.  
+**VS Code 통합** – VS Code의 탐색 및 명령 팔레트와 원활하게 통합됩니다.
+
+### 사전 관리 명령
+
+VS Code에서 직접 콘텐츠 사전을 관리하세요:
+
+- **사전 생성** (`extension.buildDictionaries`) – 프로젝트 구조를 기반으로 콘텐츠 파일을 생성합니다.
+- **사전 업로드** (`extension.pushDictionaries`) – 최신 사전 콘텐츠를 저장소에 업로드합니다.
+- **사전 동기화** (`extension.pullDictionaries`) – 최신 사전 콘텐츠를 저장소에서 로컬 환경으로 동기화합니다.
+
+### 콘텐츠 선언 생성기
+
+다양한 형식으로 구조화된 사전 파일을 쉽게 생성하세요:
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## 설치
+
+**Intlayer**를 VS Code 마켓플레이스에서 직접 설치할 수 있습니다:
+
+1. **VS Code**를 엽니다.
+2. **확장 프로그램 마켓플레이스**로 이동합니다.
+3. **"Intlayer"**를 검색합니다.
+4. **설치**를 클릭합니다.
+
+또는 명령줄을 통해 설치할 수 있습니다:
+
+```sh
+code --install-extension intlayer
+```
+
+## 사용법
+
+### 빠른 탐색
+
+1. **react-intlayer**를 사용하는 프로젝트를 엽니다.
+2. `useIntlayer()` 호출을 찾습니다. 예:
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+3. 키(예: `"app"`)를 **Command+클릭** (`⌘+Click` macOS) 또는 **Ctrl+클릭** (Windows/Linux)합니다.
+4. VS Code가 자동으로 해당 사전 파일을 엽니다. 예: `src/app.content.ts`.
+
+### 콘텐츠 사전 관리
+
+#### 사전 생성
+
+모든 사전 콘텐츠 파일을 생성하려면:
+
+```sh
+Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
+```
+
+**Build Dictionaries**를 검색하고 명령을 실행합니다.
+
+#### 사전 업로드
+
+최신 사전 콘텐츠를 업로드하려면:
+
+1. **명령 팔레트**를 엽니다.
+2. **Push Dictionaries**를 검색합니다.
+3. 업로드할 사전을 선택하고 확인합니다.
+
+#### 사전 동기화
+
+최신 사전 콘텐츠를 동기화하려면:
+
+1. **명령 팔레트**를 엽니다.
+2. **Pull Dictionaries**를 검색합니다.
+3. 동기화할 사전을 선택합니다.
+
+### 사전 파일 경로 사용자 정의
+
+기본적으로 확장은 표준 **Intlayer** 프로젝트 구조를 따릅니다. 그러나 사용자 정의 경로를 구성할 수 있습니다:
+
+1. **설정 (`Cmd + ,` macOS / `Ctrl + ,` Windows/Linux)**을 엽니다.
+2. `Intlayer`를 검색합니다.
+3. 콘텐츠 파일 경로 설정을 조정합니다.
+
+## 개발 및 기여
+
+기여하고 싶으신가요? 커뮤니티의 기여를 환영합니다!
+
+저장소 URL: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### 시작하기
+
+저장소를 복제하고 종속성을 설치하세요:
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> 확장을 빌드하고 게시하기 위한 `vsce` 패키지와의 호환성을 위해 `npm` 패키지 관리자를 사용하세요.
+
+### 개발 모드에서 실행
+
+1. **VS Code**에서 프로젝트를 엽니다.
+2. `F5`를 눌러 새로운 **확장 개발 호스트** 창을 실행합니다.
+
+### Pull Request 제출
+
+확장을 개선했다면 [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension)에 PR을 제출하세요.
+
+## 피드백 및 문제
+
+버그를 발견했거나 기능 요청이 있나요? **GitHub 저장소**에서 이슈를 열어주세요:
+
+[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## 라이선스
+
+Intlayer는 **MIT 라이선스**로 배포됩니다.

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@intlayer/docs",
+  "version": "5.5.8",
+  "private": false,
+  "description": "Intlayer documentation",
+  "keywords": [
+    "intlayer",
+    "documentation",
+    "application",
+    "typescript",
+    "javascript",
+    "json",
+    "file"
+  ],
+  "homepage": "https://intlayer.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aymericzip/intlayer.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Aymeric PINEAU",
+    "url": "https://github.com/aymericzip"
+  },
+  "contributors": [
+    {
+      "name": "Aymeric Pineau",
+      "email": "ay.pineau@gmail.com",
+      "url": "https://github.com/aymericzip"
+    }
+  ],
+  "sideEffects": false,
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.cjs",
+      "import": "./index.cjs"
+    }
+  },
+  "main": "./index.cjs",
+  "module": "./index.cjs",
+  "files": [
+    "index.d.ts",
+    "index.cjs",
+    "ar/*",
+    "de/*",
+    "en/*",
+    "en-GB/*",
+    "es/*",
+    "fr/*",
+    "hi/*",
+    "it/*",
+    "ja/*",
+    "ko/*",
+    "pt/*",
+    "ru/*",
+    "zh/*"
+  ],
+  "dependencies": {
+    "@intlayer/config": "5.5.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "concurrently": "^9.1.2",
+    "dotenv": "^16.4.7",
+    "eslint": "^9.28.0",
+    "fast-glob": "^3.3.3",
+    "openai": "^4.89.0",
+    "p-limit": "^3.1.0",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "tsc-alias": "^1.8.16",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "@intlayer/core": "5.5.8",
+    "@utils/ts-config-types": "1.0.4",
+    "@utils/tsup-config": "1.0.4",
+    "@utils/ts-config": "1.0.4"
+  },
+  "engines": {
+    "node": ">=14.18"
+  },
+  "bug": {
+    "url": "https://github.com/aymericzip/intlayer/issues"
+  },
+  "scripts": {
+    "lint": "eslint . --cache",
+    "lint:fix": "eslint . --cache --fix",
+    "prettier": "prettier . --check",
+    "prettier:fix": "prettier . --write",
+    "test": "",
+    "translate": "node --import=tsx ./src/translate.ts"
+  }
+}

package/pt/CI_CD.md

@@ -0,0 +1,149 @@
+# Geração Automática de Traduções em um Pipeline CI/CD
+
+O Intlayer permite a geração automática de traduções para seus arquivos de declaração de conteúdo. Existem várias maneiras de alcançar isso, dependendo do seu fluxo de trabalho.
+
+## Usando o CMS
+
+Com o Intlayer, você pode adotar um fluxo de trabalho onde apenas um único idioma é declarado localmente, enquanto todas as traduções são gerenciadas remotamente através do CMS. Isso permite que o conteúdo e as traduções sejam completamente desvinculados do código, oferecendo mais flexibilidade para os editores de conteúdo e permitindo recarregamento dinâmico de conteúdo (sem necessidade de reconstruir a aplicação para aplicar mudanças).
+
+### Exemplo de Configuração
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Idiomas opcionais serão gerenciados remotamente
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // Conteúdo remoto tem prioridade
+
+    applicationURL: process.env.APPLICATION_URL, // URL da aplicação usada pelo CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // Credenciais do CMS
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "Esta é uma aplicação de teste", // Ajuda a garantir consistência na geração de traduções
+  },
+};
+
+export default config;
+```
+
+Para saber mais sobre o CMS, consulte a [documentação oficial](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_CMS.md).
+
+## Usando Husky
+
+Você pode integrar a geração de traduções ao seu fluxo de trabalho local do Git usando [Husky](https://typicode.github.io/husky/).
+
+### Exemplo de Configuração
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Idiomas opcionais são gerenciados remotamente
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY, // Use sua própria chave de API
+
+    applicationContext: "Esta é uma aplicação de teste", // Ajuda a garantir consistência na geração de traduções
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Para garantir que os dicionários estejam atualizados
+npx intlayer fill --unpushed --mode fill    # Apenas preenche conteúdo ausente, não atualiza os existentes
+```
+
+> Para mais informações sobre os comandos CLI do Intlayer e seu uso, consulte a [documentação CLI](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_cli.md).
+
+> Se você tiver múltiplos aplicativos no seu repositório usando instâncias separadas do Intlayer, você pode usar o argumento `--base-dir` assim:
+
+```bash fileName=".husky/pre-push"
+# App 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# App 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## Usando GitHub Actions
+
+O Intlayer fornece um comando CLI para preencher automaticamente e revisar o conteúdo do dicionário. Isso pode ser integrado ao seu fluxo de trabalho CI/CD usando GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  workflow_dispatch: {}
+
+concurrency:
+  group: 'autofill-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
+      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: ⚙️ Build Intlayer project
+        run: npx intlayer build
+
+      - name: 🤖 Auto-fill missing translations
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 Create or update translation PR
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: auto-fill missing translations [skip ci]
+          branch: auto-translations
+          title: chore: update missing translations
+          labels: translation, automated
+```
+
+> Assim como no caso do Husky, em um monorepo, você pode usar o argumento `--base-dir` para tratar sequencialmente cada aplicativo.
+
+> Por padrão, o argumento `--git-diff` filtra dicionários que incluem alterações da base (padrão `origin/main`) para o branch atual (padrão: `HEAD`).
+
+> Para mais informações sobre os comandos CLI do Intlayer e seu uso, consulte a [documentação CLI](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_cli.md).

package/pt/autoFill.md

@@ -0,0 +1,157 @@
+# Arquivos de Declaração de Conteúdo Preenchidos Automaticamente
+
+Os **arquivos de declaração de conteúdo preenchidos automaticamente** são uma maneira de acelerar seu fluxo de trabalho de desenvolvimento.
+
+O mecanismo de preenchimento automático funciona através de uma relação _mestre-escravo_ entre os 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"
+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",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Aqui está um [arquivo de declaração de conteúdo por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/pt/per_locale_file.md) usando a instrução `autoFill`.
+
+Então, quando você executa o seguinte comando:
+
+```bash
+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 idiomas ainda não declarados no arquivo principal.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+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 de Arquivos Preenchidos 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 formatos `.ts`, `.js`, `.mjs`, `.cjs` e outros.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso gerará o arquivo em:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> A geração de arquivos `.js`, `.ts` e similares funciona da seguinte maneira:
+
+> - Se o arquivo já existir, o Intlayer o analisará usando o AST (Árvore de Sintaxe Abstrata) para localizar cada campo e inserir as traduções faltantes.
+
+> - Se o arquivo não existir, o Intlayer o gerará usando o modelo padrão para arquivos de declaração de conteúdo.
+
+## Caminhos Absolutos
+
+O campo `autoFill` também suporta caminhos absolutos.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso gerará o arquivo em:
+
+```
+/messages/example.content.json
+```
+
+## Geração Automática de Arquivos de Declaração de Conteúdo por Idioma
+
+O campo `autoFill` também suporta a geração de arquivos de declaração de conteúdo **por idioma**.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso gerará dois arquivos separados:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## Filtrar Preenchimento Automático por Idioma Específico
+
+O uso de um objeto para o campo `autoFill` permite que você aplique filtros e gere apenas arquivos de idioma específicos.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso gerará apenas o arquivo de tradução francês.
+
+## Variáveis de Caminho
+
+Você pode usar variáveis dentro do caminho `autoFill` para resolver dinamicamente os caminhos de destino para os arquivos gerados.
+
+**Variáveis disponíveis:**
+
+- `{{locale}}` – Código do idioma (ex. `fr`, `es`)
+- `{{key}}` – Chave do dicionário (ex. `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Seu conteúdo
+  },
+};
+```
+
+Isso gerará:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`