@intlayer/docs 8.0.4 → 8.0.5

package/docs/pt/intlayer_with_analog.md

@@ -0,0 +1,371 @@
+---
+createdAt: 2025-04-18
+updatedAt: 2025-12-30
+title: Analog i18n - Como traduzir sua aplicação Analog – guia 2026
+description: Descubra como tornar sua aplicação Analog multilíngue. Siga a documentação para internacionalizar (i18n) e traduzi-la.
+keywords:
+  - Internacionalização
+  - Documentação
+  - Intlayer
+  - Analog
+  - Angular
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - analog
+applicationTemplate: https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template
+history:
+  - version: 8.0.4
+    date: 2026-01-26
+    changes: Iniciar histórico
+---
+
+# Traduza sua aplicação Analog (Angular) usando Intlayer | Internacionalização (i18n)
+
+## Sumário
+
+<TOC/>
+
+## O que é Intlayer?
+
+**Intlayer** é uma biblioteca de internacionalização (i18n) inovadora e de código aberto, projetada para simplificar o suporte multilíngue em aplicações web modernas.
+
+Com o Intlayer, você pode:
+
+- **Gerenciar traduções facilmente** usando dicionários declarativos ao nível do componente.
+- **Localizar metadados, rotas e conteúdo dinamicamente**.
+- **Garantir suporte ao TypeScript** com tipos autogerados, melhorando o autocompletar e a detecção de erros.
+- **Beneficiar-se de recursos avançados**, como detecção e troca dinâmica de idioma (locale).
+
+---
+
+## Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Analog
+
+<Tabs defaultTab="code">
+  <Tab label="Código" value="code">
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer/tree/main/examples/vite-analog-app?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Como Internacionalizar sua aplicação usando Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+Veja o [Modelo de Aplicação](https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template) no GitHub.
+
+### Passo 1: Instalar Dependências
+
+Instale os pacotes necessários usando npm:
+
+```bash packageManager="npm"
+npm install intlayer angular-intlayer vite-intlayer
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer angular-intlayer vite-intlayer
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer angular-intlayer vite-intlayer
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer angular-intlayer vite-intlayer
+bunx intlayer init
+```
+
+- **intlayer**
+
+  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpilação e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
+
+- **angular-intlayer**
+  O pacote que integra o Intlayer com aplicações Angular. Ele fornece provedores de contexto e hooks para internacionalização Angular.
+
+- **vite-intlayer**
+  O pacote que integra o Intlayer com o Vite. Ele fornece um plugin para lidar com arquivos de declaração de conteúdo e configura aliases para um desempenho ideal.
+
+### Passo 2: Configuração do seu projeto
+
+Crie um arquivo de configuração para configurar os idiomas da sua aplicação:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Seus outros idiomas
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Seus outros idiomas
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Seus outros idiomas
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desativar os logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a [documentação de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
+
+### Passo 3: Integrar o Intlayer na sua Configuração do Vite
+
+Para integrar o Intlayer com o Analog, você precisa usar o plugin `vite-intlayer`.
+
+Modifique seu arquivo `vite.config.ts`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+import analog from "@analogjs/platform";
+
+// https://vitejs.dev/config/
+export default defineConfig(() => ({
+  plugins: [
+    analog(),
+    intlayer(), // Adicione o plugin Intlayer
+  ],
+}));
+```
+
+> O plugin `intlayer()` configura o Vite com o Intlayer. Ele lida com arquivos de declaração de conteúdo e configura aliases para um desempenho ideal.
+
+### Passo 4: Declarar seu Conteúdo
+
+Crie e gerencie suas declarações de conteúdo para armazenar traduções:
+
+```tsx fileName="src/app/app.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+      pt: "Olá",
+    }),
+    congratulations: t({
+      en: "Congratulations! Your app is running. 🎉",
+      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
+      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
+      pt: "Parabéns! Sua aplicação está funcionando. 🎉",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+> Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no diretório `contentDir` (por padrão, `./src`) e correspondam à extensão do arquivo de declaração de conteúdo (por padrão, `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+
+> Para mais detalhes, consulte a [documentação de declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md).
+
+### Passo 5: Utilizar o Intlayer em seu Código
+
+Para utilizar os recursos de internacionalização do Intlayer em toda a sua aplicação Analog, você precisa fornecer o Intlayer na configuração da sua aplicação.
+
+```typescript fileName="src/app/app.config.ts"
+import { ApplicationConfig } from "@angular/core";
+import { provideIntlayer } from "angular-intlayer";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideIntlayer(), // Adicione o provedor Intlayer aqui
+  ],
+};
+```
+
+Então, você pode usar a função `useIntlayer` dentro de qualquer componente.
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  template: `
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+O conteúdo do Intlayer é retornado como um `Signal`, então você acessa os valores chamando o sinal: `content().title`.
+
+### (Opcional) Passo 6: Alterar o idioma do seu conteúdo
+
+Para alterar o idioma do seu conteúdo, você pode usar a função `setLocale` fornecida pela função `useLocale`. Isso permite que você defina o idioma da aplicação e atualize o conteúdo adequadamente.
+
+Crie um componente para alternar entre idiomas:
+
+```typescript fileName="src/app/locale-switcher.component.ts"
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { useLocale } from "angular-intlayer";
+
+@Component({
+  selector: "app-locale-switcher",
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div class="locale-switcher">
+      <select
+        [value]="locale()"
+        (change)="setLocale($any($event.target).value)"
+      >
+        @for (loc of availableLocales; track loc) {
+          <option [value]="loc">{{ loc }}</option>
+        }
+      </select>
+    </div>
+  `,
+  styles: [
+    `
+      .locale-switcher {
+        margin: 1rem;
+        padding: 0.5rem;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        width: fit-content;
+      }
+    `,
+  ],
+})
+export class LocaleSwitcherComponent {
+  localeCtx = useLocale();
+
+  locale = this.localeCtx.locale;
+  availableLocales = this.localeCtx.availableLocales;
+  setLocale = this.localeCtx.setLocale;
+}
+```
+
+Então, use este componente em suas páginas:
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+import { LocaleSwitcherComponent } from "../locale-switcher.component";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  imports: [LocaleSwitcherComponent],
+  template: `
+    <app-locale-switcher></app-locale-switcher>
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+### Configurar TypeScript
+
+O Intlayer usa o aumento de módulo (module augmentation) para obter benefícios do TypeScript e tornar sua base de código mais robusta.
+
+![Autocompletar](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Erro de tradução](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Certifique-se de que sua configuração do TypeScript inclua os tipos autogerados.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Suas configurações existentes do TypeScript
+  "include": [
+    // ... Suas configurações existentes do TypeScript
+    ".intlayer/**/*.ts", // Incluir os tipos autogerados
+  ],
+}
+```
+
+### Configuração do Git
+
+Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite commitá-los no seu repositório Git.
+
+Para fazer isso, você pode adicionar as seguintes instruções ao seu arquivo `.gitignore`:
+
+```plaintext
+# Ignorar os arquivos gerados pelo Intlayer
+.intlayer
+```
+
+### Extensão do VS Code
+
+Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a **Extensão oficial do Intlayer para o VS Code**.
+
+[Instalar a partir do VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+Esta extensão fornece:
+
+- **Autocompletar** para chaves de tradução.
+- **Detecção de erros em tempo real** para traduções ausentes.
+- **Visualizações inline** do conteúdo traduzido.
+- **Ações rápidas** para criar e atualizar traduções facilmente.
+
+Para mais detalhes sobre como usar a extensão, consulte a [documentação da Extensão Intlayer para o VS Code](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Indo Além
+
+Para ir além, você pode implementar o [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) ou externalizar seu conteúdo usando o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).

package/docs/pt/intlayer_with_angular.md

@@ -166,30 +166,28 @@ Para integrar o Intlayer com o Angular CLI, você precisa usar um builder person
 
 Primeiro, modifique seu `angular.json` para usar o builder personalizado do Webpack. Atualize as configurações de `build` e `serve`:
 
-```json fileName="angular.json"
+```json5 fileName="angular.json"
 {
   "projects": {
     "your-app-name": {
       "architect": {
         "build": {
-          "builder": "@angular-builders/custom-webpack:browser",
+          "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",
           "options": {
             "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
+              "path": "./webpack.config.ts",
+              "mergeStrategies": { "module.rules": "prepend" },
+            },
+            "main": "src/main.ts", // replace "browser": "src/main.ts",
+            // ...
+          },
         },
         "serve": {
           "builder": "@angular-builders/custom-webpack:dev-server",
-          "options": {
-            "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
-        }
-      }
-    }
-  }
+        },
+      },
+    },
+  },
 }
 ```
 

package/docs/pt/packages/solid-intlayer/useIntlayer.md

@@ -33,7 +33,7 @@ O hook `useIntlayer` permite recuperar conteúdo localizado de um dicionário us
 import { useIntlayer } from "solid-intlayer";
 
 const MyComponent = () => {
-  const content = useIntlayer("my_dictionary_key");
+  const content = useIntlayer("my-dictionary-key");
 
   return (
     <div>

package/docs/ru/cli/doc-translate.md

@@ -86,6 +86,7 @@ npx intlayer doc translate
 - **`--temperature [temperature]`**: Параметр температуры для модели ИИ.
 - **`--api-key [apiKey]`**: Предоставьте свой собственный API-ключ для сервиса ИИ.
 - **`--application-context [applicationContext]`**: Предоставьте дополнительный контекст для перевода ИИ.
+- **`--data-serialization [dataSerialization]`**: Формат сериализации данных для использования в функциях ИИ Intlayer. Опции: `json` (стандартный, надежный), `toon` (меньше токенов, менее стабильный).
 - **`--custom-prompt [prompt]`**: Настройка базового запроса, используемого для перевода. (Примечание: для большинства случаев рекомендуется использовать опцию `--custom-instructions`, так как она обеспечивает лучший контроль над поведением перевода.)
 
   > Пример: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "Мое приложение — магазин для кошек"`

package/docs/ru/cli/fill.md

@@ -126,6 +126,7 @@ Affected dictionary keys for processing: app, comp-test, hello-world, lang-switc
 - **`--api-key [apiKey]`**: Предоставить собственный API-ключ для сервиса ИИ.
 - **`--custom-prompt [prompt]`**: Предоставить пользовательский запрос для инструкций по переводу.
 - **`--application-context [applicationContext]`**: Предоставить дополнительный контекст для перевода ИИ.
+- **`--data-serialization [dataSerialization]`**: Формат сериализации данных для использования в функциях ИИ Intlayer. Опции: `json` (стандартный, надежный), `toon` (меньше токенов, менее стабильный).
 
   > Пример: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "Моё приложение — магазин для кошек"`
 

package/docs/ru/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: Добавление `dataSerialization` в конфигурацию ИИ
   - version: 8.0.0
     date: 2026-01-22
     changes: Move `importMode` build configuration to `dictionary` configuration.
@@ -311,6 +314,14 @@ const config: IntlayerConfig = {
      * Base URL for the AI API.
      */
     baseURL: "http://localhost:3000",
+
+    /**
+     * Data serialization format to use for the AI features of Intlayer.
+     * - "json": The industry standard. Highly reliable and structured, but consumes more tokens.
+     * - "toon": An optimized format designed to reduce token consumption (cost-effective). However, it may slightly increase the risk of output inconsistency compared to standard JSON
+     * Default: "json"
+     */
+    dataSerialization: "json",
   },
 
   /**
@@ -892,6 +903,13 @@ Intlayer поддерживает несколько провайдеров ИИ
   - _Пример_: `'https://api.openai.com/v1'`
   - _Примечание_: Может использоваться для указания локальной или пользовательской конечной точки API ИИ.
 
+- **dataSerialization**:
+  - _Тип_: `'json' | 'toon'`
+  - _По умолчанию_: `'json'`
+  - _Описание_: Формат сериализации данных для использования в функциях ИИ Intlayer.
+  - _Пример_: `'toon'`
+  - _Примечание_: `json`: Стандартный, надежный; использует больше токенов. `toon`: Меньше токенов, менее стабильный, чем JSON.
+
 ### Конфигурация сборки
 
 Настройки, которые контролируют, как Intlayer оптимизирует и собирает интернационализацию вашего приложения.