@intlayer/docs 5.5.8

package/en-GB/vs_code_extension.md

@@ -0,0 +1,139 @@
+# Official VS Code Extension
+
+## Overview
+
+**Intlayer** is the official Visual Studio Code extension for **Intlayer**, designed to enhance the developer experience when working with localised content in **React, Next.js, and JavaScript** projects.
+
+With this extension, developers can **quickly navigate** to their content dictionaries, manage localisation files, and streamline their workflow with powerful automation commands.
+
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+
+Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
+
+## Features
+
+### Instant Navigation
+
+**Go to Definition Support** – Use `Cmd+Click` (Mac) or `Ctrl+Click` (Windows/Linux) on a `useIntlayer` key to open the corresponding content file instantly.  
+**Seamless Integration** – Works effortlessly with **react-intlayer** and **next-intlayer** projects.  
+**Multi-language Support** – Supports localised content across different languages.  
+**VS Code Integration** – Smoothly integrates with VS Code’s navigation and command palette.
+
+### Dictionary Management Commands
+
+Manage your content dictionaries directly from VS Code:
+
+- **Build Dictionaries** (`extension.buildDictionaries`) – Generate content files based on your project structure.
+- **Push Dictionaries** (`extension.pushDictionaries`) – Upload the latest dictionary content to your repository.
+- **Pull Dictionaries** (`extension.pullDictionaries`) – Sync the latest dictionary content from your repository to your local environment.
+
+### Content Declaration Generator
+
+Easily generate structured dictionary files in different formats:
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## Installation
+
+You can install **Intlayer** directly from the VS Code Marketplace:
+
+1. Open **VS Code**.
+2. Go to the **Extensions Marketplace**.
+3. Search for **"Intlayer"**.
+4. Click **Install**.
+
+Alternatively, install it via the command line:
+
+```sh
+code --install-extension intlayer
+```
+
+## Usage
+
+### Quick Navigation
+
+1. Open a project using **react-intlayer**.
+2. Locate a call to `useIntlayer()`, such as:
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+3. **Command-click** (`⌘+Click` on macOS) or **Ctrl+Click** (on Windows/Linux) on the key (e.g., `"app"`).
+4. VS Code will automatically open the corresponding dictionary file, e.g., `src/app.content.ts`.
+
+### Managing Content Dictionaries
+
+#### Building Dictionaries
+
+Generate all dictionary content files with:
+
+```sh
+Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
+```
+
+Search for **Build Dictionaries** and execute the command.
+
+#### Pushing Dictionaries
+
+Upload the latest dictionary content:
+
+1. Open the **Command Palette**.
+2. Search for **Push Dictionaries**.
+3. Select the dictionaries to push and confirm.
+
+#### Pulling Dictionaries
+
+Sync the latest dictionary content:
+
+1. Open the **Command Palette**.
+2. Search for **Pull Dictionaries**.
+3. Choose the dictionaries to pull.
+
+### Customising Dictionary File Paths
+
+By default, the extension follows the standard **Intlayer** project structure. However, you can configure custom paths:
+
+1. Open **Settings (`Cmd + ,` on macOS / `Ctrl + ,` on Windows/Linux)`**.
+2. Search for `Intlayer`.
+3. Adjust the content file path setting.
+
+## Development & Contribution
+
+Want to contribute? We welcome community contributions!
+
+Repo URL: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### Getting Started
+
+Clone the repository and install dependencies:
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> Use `npm` package manager for compatibility with `vsce` package to build and publish the extension.
+
+### Run in Development Mode
+
+1. Open the project in **VS Code**.
+2. Press `F5` to launch a new **Extension Development Host** window.
+
+### Submit a Pull Request
+
+If you improve the extension, submit a PR on [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension).
+
+## Feedback & Issues
+
+Found a bug or have a feature request? Open an issue on our **GitHub repository**:
+
+[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## License
+
+Intlayer is released under the **MIT License**.

package/es/CI_CD.md

@@ -0,0 +1,149 @@
+# Generación Automática de Traducciones en un Pipeline CI/CD
+
+Intlayer permite la generación automática de traducciones para tus archivos de declaración de contenido. Hay múltiples formas de lograr esto dependiendo de tu flujo de trabajo.
+
+## Usando el CMS
+
+Con Intlayer, puedes adoptar un flujo de trabajo donde solo se declara un único locale localmente, mientras que todas las traducciones se gestionan de forma remota a través del CMS. Esto permite que el contenido y las traducciones estén completamente desvinculados del código, ofreciendo más flexibilidad para los editores de contenido y habilitando la recarga en caliente del contenido (sin necesidad de reconstruir la aplicación para aplicar cambios).
+
+### Ejemplo de Configuración
+
+```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], // Los locales opcionales se gestionarán de forma remota
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // El contenido remoto tiene prioridad
+
+    applicationURL: process.env.APPLICATION_URL, // URL de la aplicación utilizada por el CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // Credenciales del CMS
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "Esta es una aplicación de prueba", // Ayuda a garantizar la generación consistente de traducciones
+  },
+};
+
+export default config;
+```
+
+Para obtener más información sobre el CMS, consulta la [documentación oficial](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_CMS.md).
+
+## Usando Husky
+
+Puedes integrar la generación de traducciones en tu flujo de trabajo local de Git utilizando [Husky](https://typicode.github.io/husky/).
+
+### Ejemplo de Configuración
+
+```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], // Los locales opcionales se gestionan de forma remota
+    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, // Usa tu propia clave API
+
+    applicationContext: "Esta es una aplicación de prueba", // Ayuda a garantizar la generación consistente de traducciones
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Para asegurar que los diccionarios estén actualizados
+npx intlayer fill --unpushed --mode fill    # Solo llena contenido faltante, no actualiza los existentes
+```
+
+> Para más información sobre los comandos de Intlayer CLI y su uso, consulta la [documentación CLI](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_cli.md).
+
+> Si tienes múltiples aplicaciones en tu repositorio usando instancias separadas de Intlayer, puedes usar el argumento `--base-dir` de esta manera:
+
+```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
+
+Intlayer proporciona un comando CLI para autofill y revisar el contenido de los diccionarios. Esto puede integrarse en tu flujo de trabajo CI/CD utilizando 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
+```
+
+> Al igual que con Husky, en el caso de un monorepo, puedes usar el argumento `--base-dir` para tratar secuencialmente cada aplicación.
+
+> Por defecto, el argumento `--git-diff` filtra los diccionarios que incluyen cambios desde la base (por defecto `origin/main`) hasta la rama actual (por defecto: `HEAD`).
+
+> Para más información sobre los comandos de Intlayer CLI y su uso, consulta la [documentación CLI](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_cli.md).

package/es/autoFill.md

@@ -0,0 +1,157 @@
+# Archivos de Declaración de Contenido Autocompletados
+
+Los **archivos de declaración de contenido autocompletados** son una forma de acelerar tu flujo de trabajo de desarrollo.
+
+El mecanismo de autocompletado funciona a través de una relación _maestro-esclavo_ entre los archivos de declaración de contenido. Cuando el archivo principal (maestro) se actualiza, Intlayer aplicará automáticamente esos cambios a los archivos de declaración derivados (autocompletados).
+
+```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;
+```
+
+Aquí hay un [archivo de declaración de contenido por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/es/per_locale_file.md) usando la instrucción `autoFill`.
+
+Luego, cuando ejecutes el siguiente comando:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer generará automáticamente el archivo de declaración derivado en `src/components/example/example.content.json`, completando todos los idiomas que aún no están declarados en el archivo 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 archivos de declaración se fusionarán en un solo diccionario, accesible usando el hook estándar `useIntlayer("example")` (react) / composable (vue).
+
+## Formato de Archivos Autocompletados
+
+El formato recomendado para los archivos de declaración autocompletados es **JSON**, lo que ayuda a evitar restricciones de formato. Sin embargo, Intlayer también admite formatos `.ts`, `.js`, `.mjs`, `.cjs` y otros.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // Tu contenido
+  },
+};
+```
+
+Esto generará el archivo en:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> La generación de archivos `.js`, `.ts` y similares funciona de la siguiente manera:
+
+> - Si el archivo ya existe, Intlayer lo analizará usando el AST (Árbol de Sintaxis Abstracta) para localizar cada campo e insertar las traducciones faltantes.
+
+> - Si el archivo no existe, Intlayer lo generará usando la plantilla predeterminada para archivos de declaración de contenido.
+
+## Rutas Absolutas
+
+El campo `autoFill` también admite rutas absolutas.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // Tu contenido
+  },
+};
+```
+
+Esto generará el archivo en:
+
+```
+/messages/example.content.json
+```
+
+## Generación Automática de Archivos de Declaración de Contenido por Idioma
+
+El campo `autoFill` también admite la generación de archivos de declaración de contenido **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: {
+    // Tu contenido
+  },
+};
+```
+
+Esto generará dos archivos separados:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## Filtrar Autocompletado por Idioma Específico
+
+El uso de un objeto para el campo `autoFill` te permite aplicar filtros y generar solo archivos de idioma específicos.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Tu contenido
+  },
+};
+```
+
+Esto solo generará el archivo de traducción francés.
+
+## Variables de Ruta
+
+Puedes usar variables dentro de la ruta `autoFill` para resolver dinámicamente las rutas objetivo de los archivos generados.
+
+**Variables disponibles:**
+
+- `{{locale}}` – Código de idioma (ej. `fr`, `es`)
+- `{{key}}` – Clave del diccionario (ej. `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Tu contenido
+  },
+};
+```
+
+Esto generará:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`