@intlayer/docs 5.7.7 → 5.8.0-canary.0

package/docs/pt/CI_CD.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-05-20
-updatedAt: 2025-06-29
+updatedAt: 2025-08-13
 title: Integração CI/CD
 description: Aprenda como integrar o Intlayer em seu pipeline CI/CD para gerenciamento e implantação automatizados de conteúdo.
 keywords:
@@ -19,13 +19,13 @@ slugs:
 
 # 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.
+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 realizar 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 fiquem completamente desacoplados da base de código, oferecendo mais flexibilidade para os editores de conteúdo e possibilitando recarregamento dinâmico do conteúdo (sem necessidade de reconstruir a aplicação para aplicar as mudanças).
+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 fiquem completamente desacoplados da base de código, oferecendo mais flexibilidade para os editores de conteúdo e possibilitando o recarregamento dinâmico do conteúdo (sem necessidade de reconstruir a aplicação para aplicar as alterações).
 
-### Exemplo de Configuração
+### Configuração de Exemplo
 
 ```ts fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -37,7 +37,7 @@ const config: IntlayerConfig = {
     defaultLocale: Locales.ENGLISH,
   },
   editor: {
-    dictionaryPriorityStrategy: "distant_first", // O conteúdo remoto tem prioridade
+    dictionaryPriorityStrategy: "distant_first", // Conteúdo remoto tem prioridade
 
     applicationURL: process.env.APPLICATION_URL, // URL da aplicação usada pelo CMS
 
@@ -45,7 +45,7 @@ const config: IntlayerConfig = {
     clientSecret: process.env.INTLAYER_CLIENT_SECRET,
   },
   ai: {
-    applicationContext: "Esta é uma aplicação de teste", // Ajuda a garantir a geração consistente de traduções
+    applicationContext: "This is a test application", // Ajuda a garantir a geração consistente de traduções
   },
 };
 
@@ -56,9 +56,9 @@ Para saber mais sobre o CMS, consulte a [documentação oficial](https://github.
 
 ## Usando Husky
 
-Você pode integrar a geração de traduções ao seu fluxo de trabalho Git local usando o [Husky](https://typicode.github.io/husky/).
+Você pode integrar a geração de traduções no seu fluxo de trabalho local do Git usando o [Husky](https://typicode.github.io/husky/).
 
-### Exemplo de Configuração
+### Configuração de Exemplo
 
 ```ts fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -77,7 +77,7 @@ const config: IntlayerConfig = {
     provider: "openai",
     apiKey: process.env.OPENAI_API_KEY, // Use sua própria chave API
 
-    applicationContext: "Esta é uma aplicação de teste", // Ajuda a garantir a geração consistente de traduções
+    applicationContext: "This is a test application", // Ajuda a garantir a geração consistente de traduções
   },
 };
 
@@ -86,7 +86,7 @@ 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    # Preenche apenas o conteúdo faltante, não atualiza os existentes
+npx intlayer fill --unpushed --mode fill    # Apenas preenche o conteúdo faltante, 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/docs/pt/intlayer_cli.md).
@@ -105,68 +105,94 @@ npx intlayer fill --base-dir ./app2 --unpushed --mode fill
 
 ## Usando GitHub Actions
 
-Intlayer fornece um comando CLI para preenchimento automático e revisão do conteúdo do dicionário. Isso pode ser integrado ao seu fluxo de trabalho CI/CD usando GitHub Actions.
+O Intlayer fornece um comando CLI para preenchimento automático e revisão do 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
+name: Preenchimento Automático Intlayer
+# Condições de gatilho para este fluxo de trabalho
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'src/**'
   pull_request:
-    branches: [ main ]
-    paths:
-      - 'src/**'
-  workflow_dispatch: {}
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
 
 concurrency:
-  group: 'autofill-${{ github.ref }}'
+  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 }}
+      # OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
-      - name: ⬇️ Fazer checkout do repositório
-        uses: actions/checkout@v3
+      # Passo 1: Obter o código mais recente do repositório
+      - name: ⬇️ Checkout do repositório
+        uses: actions/checkout@v4
         with:
-          persist-credentials: true
+          persist-credentials: true # Manter credenciais para criação de PRs
+          fetch-depth: 0 # Obter histórico completo do git para análise de diferenças
 
+      # Passo 2: Configurar ambiente Node.js
       - name: 🟢 Configurar Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 20 # Usar Node.js 20 LTS para estabilidade
 
+      # Passo 3: Instalar dependências do projeto
       - name: 📦 Instalar dependências
-        run: npm ci
+        run: npm install
+
+      # Passo 4: Instalar Intlayer CLI globalmente para gerenciamento de traduções
+      - name: 📦 Instalar Intlayer
+        run: npm install -g intlayer-cli
 
+      # Passo 5: Construir o projeto Intlayer para gerar arquivos de tradução
       - name: ⚙️ Construir projeto Intlayer
         run: npx intlayer build
 
+      # Passo 6: Usar IA para preencher automaticamente traduções faltantes
       - name: 🤖 Preencher automaticamente traduções faltantes
-        run: npx intlayer fill --git-diff --mode fill
-
-      - name: 📤 Criar ou atualizar PR de tradução
-        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
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Passo 7: Verificar se há alterações e comitá-las
+      - name: � Verificar alterações
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Passo 8: Comitar e enviar alterações se existirem
+      - name: 📤 Comitar e enviar alterações
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: auto-fill missing translations [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
 ```
 
+Para configurar as variáveis de ambiente, vá para GitHub → Configurações → Segredos e variáveis → Ações e adicione o segredo .
+
 > Assim como para o Husky, no caso de um monorepo, você pode usar o argumento `--base-dir` para tratar sequencialmente cada app.
 
 > Por padrão, o argumento `--git-diff` filtra os 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 do Intlayer CLI e seu uso, consulte a [documentação do CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_cli.md).
 
-## Histórico da Documentação
+## Histórico do Documento
 
-- 5.5.10 - 2025-06-29: Histórico inicial
+| Versão | Data       | Alterações        |
+| ------ | ---------- | ----------------- |
+| 5.5.10 | 2025-06-29 | Histórico inicial |

package/docs/pt/formatters.md

@@ -0,0 +1,239 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: Formatadores
+description: Utilitários de formatação sensíveis à localidade baseados no Intl para números, percentuais, moeda, datas, tempo relativo, unidades e notação compacta. Inclui um helper Intl com cache.
+keywords:
+  - Formatadores
+  - Intl
+  - Número
+  - Moeda
+  - Percentual
+  - Data
+  - Tempo Relativo
+  - Unidades
+  - Compacto
+  - Internacionalização
+slugs:
+  - doc
+  - formatters
+---
+
+# Formatadores Intlayer
+
+## Visão Geral
+
+O Intlayer fornece um conjunto de helpers leves construídos sobre as APIs nativas `Intl`, além de um wrapper `Intl` com cache para evitar a construção repetida de formatadores pesados. Esses utilitários são totalmente sensíveis à localidade e podem ser usados a partir do pacote principal `intlayer`.
+
+### Importação
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+Se você estiver usando React, hooks também estão disponíveis; veja `react-intlayer/format`.
+
+## Intl com Cache
+
+O `Intl` exportado é um wrapper leve com cache em torno do `Intl` global. Ele memoiza instâncias de `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, o que evita reconstruir o mesmo formatador repetidamente.
+
+Como a construção do formatador é relativamente custosa, esse cache melhora a performance sem alterar o comportamento. O wrapper expõe a mesma API do `Intl` nativo, então o uso é idêntico.
+
+- O cache é por processo e transparente para os chamadores.
+
+> Se `Intl.DisplayNames` não estiver disponível no ambiente, um único aviso para desenvolvedores é exibido (considere usar um polyfill).
+
+Exemplo:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## Formatadores
+
+Todos os helpers abaixo são exportados do `intlayer`.
+
+### `number(value, options?)`
+
+Formata um valor numérico usando agrupamento e decimais sensíveis ao local.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Exemplos:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789" (em en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+Formata um número como uma string percentual.
+
+Comportamento: valores maiores que 1 são interpretados como percentagens inteiras e normalizados (por exemplo, `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Exemplos:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+Formata um valor como moeda localizada. O padrão é `USD` com duas casas decimais.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Campos comuns: `currency` (por exemplo, `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+Exemplos:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1.234,50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+Formata um valor de data/hora com `Intl.DateTimeFormat`.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` ou um dos predefinidos:
+  - Predefinidos: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+Exemplos:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // ex., "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+Formata o tempo relativo entre dois instantes com `Intl.RelativeTimeFormat`.
+
+- Passe "now" como o primeiro argumento e o alvo como o segundo para obter uma frase natural.
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (padrão é `new Date()`)
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - O `unit` padrão é `"second"`.
+
+Exemplos:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "em 3 dias"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "há 2 horas"
+```
+
+### `units(value, options?)`
+
+Formata um valor numérico como uma string de unidade localizada usando `Intl.NumberFormat` com `style: 'unit'`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Campos comuns: `unit` (ex.: `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+  - Padrões: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
+
+Exemplos:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 quilômetros"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1.024B" (dependente do locale)
+```
+
+### `compact(value, options?)`
+
+Formata um número usando notação compacta (ex.: `1.2K`, `1M`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (usa `notation: 'compact'` internamente)
+
+Exemplos:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 milhão"
+```
+
+## Notas
+
+- Todos os helpers aceitam entradas do tipo `string`; elas são internamente convertidas para números ou datas.
+- O locale padrão é o configurado em `internationalization.defaultLocale` caso não seja fornecido.
+- Essas utilidades são wrappers simples; para formatações avançadas, utilize as opções padrão do `Intl`.
+
+## Pontos de entrada e reexportações (`@index.ts`)
+
+Os formatadores estão no pacote core e são reexportados por pacotes de nível superior para manter os imports ergonômicos em diferentes runtimes:
+
+Exemplos:
+
+```ts
+// Código da aplicação (recomendado)
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+Componentes cliente:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// ou em apps Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+Componentes servidor (ou runtime React Server):
+
+```ts
+import { useNumber, useCurrency, useDate } from "intlayer/server/format";
+// ou em apps Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> Esses hooks considerarão o locale do `IntlayerProvider` ou `IntlayerServerProvider`
+
+## Histórico da documentação
+
+| Versão | Data       | Alterações                             |
+| ------ | ---------- | -------------------------------------- |
+| 5.8.0  | 2025-08-18 | Adiciona documentação dos formatadores |