---
title: "Executar traduções"
description: "translate, watch e os pontos de entrada em torno de uma execução, além de pseudolocales e catálogos tipados, tudo disponível para os seus scripts Node.js."
type: "reference"
---
# Executar traduções

translate, watch e os pontos de entrada em torno de uma execução, além de pseudolocales e catálogos tipados, tudo disponível para os seus scripts Node.js.

## Traduzir e observar [#run-translations]

### translate [#translate]

O fluxo de execução única: lê a origem, compara cada locale de destino com a linha de base do arquivo de lock, envia ao provedor as chaves ausentes e alteradas, executa as verificações de integridade, grava os arquivos de locale e atualiza o arquivo de lock. Use-o em scripts, etapas de build e jobs de CI.

```ts title="Assinatura"
function translate(
  input: TranslateInput,
  deps?: TranslateDeps,
): Promise<RunSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against, and where the lock-file, the translation memory, and the run-status file live. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the run to a subset of the configured target locales, which is how you translate one locale at a time against a rate-limited provider. Defaults to every configured target. The result keeps the configured order whatever order the subset is given in, and any locale named here that is not a configured target fails the whole run with `UNKNOWN_LOCALE` before anything is read or spent. An explicit empty array selects no locale at all rather than every locale. Locales left out are untouched: their files, their lock entries, and their translation-memory entries all stay as they were. The run-status file always describes the most recent run alone, so a subset run narrows it to that subset. |
| `dryRun` | `boolean` | no | Compute the whole run but write nothing and call no provider. The returned RunSummary reports what would have happened, which makes this safe to run in CI to preview work without spending anything. Defaults to false. In human-only mode (provider `none`) it reads the translation memory, so the plan matches a live run. |
| `estimate` | `boolean` | no | Compute a pre-run cost estimate and return it on RunSummary.estimate. Implies `dryRun`: an estimate constructs no provider, reads no API key, makes no network call, and writes no file, so it is safe to run anywhere. Defaults to false. The figure bounds the plan rather than the invoice: every provider call a live run schedules is counted, plural generation included, and the prompt is measured from the request payload that would be sent. Provider-side retries, a repair round, and a language that expands past the allowance can each push a live run above it; EstimateCaveatCode names them all. It carries a currency amount only when the config supplies a `rates` block covering the configured provider and model; otherwise it reports the quantity and says why the money is missing. See RunEstimate. |
| `prune` | `boolean` | no | Remove keys that no longer exist in the source. Defaults to the config's `prune`, then to false, so orphaned keys are reported but kept unless removal is asked for explicitly. |
| `generatePlurals` | `boolean` | no | Generate the plural categories a target language requires rather than translating each category separately. Defaults to the config's `generatePlurals`, then to false. Takes effect only for the `i18next-json` format with an LLM provider; any other format, a machine-translation provider, and provider `none` generate nothing. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock, so a CLI can explain a stall instead of appearing to hang. Never called for a lock this process holds itself, such as the lock-file guard a sibling locale holds on a concurrent run. Fires first once a wait has lasted a second. The SDK writes no output itself. |
| `onProgress` | `ProgressListener` | no | Called as locales and sub-batches start and finish, for progress reporting. The SDK writes no output itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock before that locale fails with `LOCK_CONTENDED`, and for the lock-file guard before a locale whose respelled state could not be moved fails with `LOCALE_STATE_NOT_CARRIED_OVER`. Both waits happen before any provider call. Defaults to ten minutes. It does not bound the lock-file guard a locale takes to record its result once its target file is written: that wait always allows the ten-minute default, so a written file is not left unrecorded. Not used on a dry run, which takes no lock. |
| `concurrency` | `number` | no | How many locales to run at once. Must be an integer of at least 1; defaults to 1. On a live run it cannot be combined with a token budget, configured or passed as `maxTokens`: the ceiling would still hold, but which locale loses its remaining work would depend on the order the locales interleave, so the run would not be reproducible. A whole-run error raised once locales are running starts no further locale, and the locales in flight finish and release their write locks before `translate` rejects, so the rejection arrives after the slowest one. |
| `cache` | `boolean` | no | Consult and update the translation memory, fuzzy reuse included. Defaults to true. Turning it off forces every key through the provider, which is what to do when you want to re-pay for a fresh translation. A dry run never reads the memory, whatever this says, except in human-only mode (provider `none`), where the memory is all a live run would use. The memory is the local CACHE_FILE_NAME file; `false` is the CLI's `--no-cache`. |
| `humanEdits` | `"overwrite" \| "protect" \| "suggest"` | no | Overrides the config's `humanEdits` for this run only (see HumanEditsPolicy). Set `overwrite` to retranslate stale keys a person wrote, as the CLI's `--include-human` flag does. Keys matching the config's `pinnedKeys` stay protected whatever this says. A dry run reads the provenance file too, unless this resolves to `overwrite`. |
| `maxTokens` | `number` | no | A token ceiling for this run alone, as the CLI's `--max-tokens` flag sets it. It is always a hard stop: a provider request that would pass it is withheld rather than sent, whatever the config's `budgetBehavior` says, and its keys are listed in LocaleSummary.budgetWithheld. When the config also sets `maxTokens`, the lower of the two applies, so this can tighten the configured budget but never loosen it. Must be a whole number of at least 1. Defaults to the config's `maxTokens` and `budgetBehavior` alone. |
| `signal` | `AbortSignal` | no | Cancels the run when aborted. No further locale starts, and a wait for a write lock stops. The locales running at the time send no further request, and an in-flight request is abandoned rather than counted as a provider failure, unless the provider reported a failure of its own. What already arrived is still written and recorded, the keys left over get no lock-file entry and stay pending for the next run, the run status is recorded, and every lock is released. The call then resolves rather than rejects: the result carries RunSummary.cancelled, each locale kept from starting is `failed` with the `RUN_CANCELLED` error code, and locales stopped while running carry a `RUN_CANCELLED` notice and are `partial`, or `failed` when no key landed and others were withheld. A dry run only stops early. Defaults to none. |

**Retorna:** [`RunSummary`](https://verbatra.kreitz-webdev.de/pt-BR/docs/sdk/run-summary.md)

**Lança:** [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#unknown_locale), [`LOCALE_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_unsupported_by_provider), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#unknown_format), [`CONCURRENCY_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#concurrency_invalid), [`CONCURRENCY_BUDGET_CONFLICT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#concurrency_budget_conflict), [`MAX_TOKENS_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#max_tokens_invalid), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#lock_timeout_invalid), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_invalid), [`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#provider_construction_failed), [`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#network_policy_violation), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#config_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#provenance_file_invalid)

**Exemplo:** [Traduzir e ler o resumo](https://verbatra.kreitz-webdev.de/pt-BR/docs/sdk-quickstart.md#traduzir-e-ler-o-resumo)

O que a tabela não cobre:

- `cache` é o cache local de memória de tradução (`verbatra.cache.json`, também exportado como `CACHE_FILE_NAME`); veja [O cache de tradução](https://verbatra.kreitz-webdev.de/pt-BR/docs/the-cache.md).
- `humanEdits` (requer a 0.12.0 ou mais recente): por padrão, as chaves obsoletas que uma pessoa escreveu, importou ou alterou fora do verbatra são mantidas e listadas em `LocaleSummary.protected`. Veja [Manter traduções humanas](https://verbatra.kreitz-webdev.de/pt-BR/docs/protecting-human-translations.md).
- `onProgress` recebe os eventos de progresso abaixo (veja [Eventos de progresso](#eventos-de-progresso)).
- `maxBatchSize` e `budgetBehavior` existem só na configuração; não há substituição por execução.

Um problema que afeta a execução inteira lança um `SdkError`; a falha de um único locale nunca lança um erro e aparece como `status: "failed"` na entrada desse locale enquanto a execução continua. Veja [A anatomia do RunSummary](https://verbatra.kreitz-webdev.de/pt-BR/docs/sdk/run-summary.md#a-anatomia-do-runsummary).

### Eventos de progresso [#eventos-de-progresso]

<AvailableFrom version="0.12.0" />

O `onProgress` recebe um `ProgressEvent`, uma união discriminada por `type`. Uma versão minor pode acrescentar tipos, então ignore um que você não reconheça.

| `type` | Quando | Campos |
| --- | --- | --- |
| `locale-started` | o trabalho de um locale começa | `locale`, `localeIndex`, `totalLocales` |
| `locale-planned` | depois que a memória de tradução é consultada, antes de o primeiro lote ser enviado; só quando um provedor é chamado | `locale`, `keys`, `batches`, `cacheHits` |
| `sub-batch` | logo antes de cada lote de tradução ser tentado | `locale`, `batchIndex`, `totalBatches` |
| `provider-retry` | um provedor embutido tenta de novo uma requisição que falhou com um status que permite nova tentativa | `attempt`, `delayMs?`, `status?` |
| `repair` | um provedor de LLM pede de novo as chaves que sua primeira resposta deixou de fora | `locale`, `keys` |
| `split-retry` | um lote cuja saída foi cortada é tentado de novo em duas metades | `locale`, `keys` |
| `batch-finished` | um lote terminou, tenha dado certo ou não | `locale`, `batchIndex`, `totalBatches`, `durationMs`, `usage?` |
| `writing` | logo antes de o arquivo de um locale ser gravado | `locale` |
| `locale-finished` | o trabalho de um locale termina | `locale`, `status`, `translated`, `localeIndex`, `totalLocales` |
| `run-finished` | todos os locales terminaram | `localesCompleted`, `localesFailed` |
| `change-detected` | só no `watch`: uma alteração no arquivo de origem se estabilizou | `paths` |
| `idle` | só no `watch`: uma execução terminou e nenhuma está na fila | nenhum |

O `provider-retry` não nomeia nenhum locale, porque um único provedor atende a execução inteira. O Gemini informa o atraso e o status; o Anthropic, o OpenAI, o OpenCode e o openai-compatible informam a tentativa no momento em que o cliente deles a inicia; e o DeepL, o Google Cloud Translation e o LibreTranslate não informam nenhum dos dois. Uma simulação e uma estimativa emitem apenas `locale-started`, `locale-finished` e `run-finished`. Os registros de progresso do `--json` da CLI ficam nos quatro tipos originais: `locale-started`, `sub-batch`, `locale-finished` e `run-finished`.

O `extract`, o `diff` com `unused` e o `doctor` com `literals` recebem um `onProgress` próprio. Ele recebe um `ScanProgressEvent`, `{ type: "files-scanned", scanned, total }`, uma vez após cada arquivo de código-fonte do aplicativo que a varredura lê.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"files-scanned"` | yes | Discriminant, reserved so later scan events can join a union. |
| `scanned` | `number` | yes | How many files have been scanned so far. |
| `total` | `number` | yes | How many files the scan will read in total. |

Um `CreateProvider` personalizado recebe um terceiro argumento, `CreateProviderHooks`, sempre que uma execução informa progresso. Chame o `onRetry` dele com `{ attempt, delayMs?, status? }` e as novas tentativas do seu provedor aparecem como eventos `provider-retry`.

### resolveDryRun [#resolvedryrun]

<AvailableFrom version="0.11.0" />

Responde se um conjunto de opções de execução equivale a uma simulação. Recebe o `dryRun` e o `estimate` que você está prestes a passar ao `translate` e retorna se essa execução vai instanciar um provedor, gravar um arquivo ou gastar alguma coisa. É o único lugar em que se decide a regra de que `estimate` implica `dryRun`, então recorra a ele sempre que algo em volta de uma execução precisar saber de antemão, em vez de repetir a implicação e se afastar dela.

```ts title="Assinatura"
function resolveDryRun(input: {
  readonly dryRun?: boolean | undefined;
  readonly estimate?: boolean | undefined;
}): boolean;
```

**Retorna:** `boolean`

```ts title="Exemplo"
import { resolveDryRun, translate, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

const options = { dryRun: false, estimate: true };
resolveDryRun(options); // true

const summary = await translate({ config, ...options });
```

### watch [#watch]

Observa o arquivo de locale de origem e executa `translate` de novo a cada alteração com debounce. Dispara uma execução inicial logo na inicialização e depois uma execução por alteração estabilizada. As execuções são serializadas: as alterações durante uma execução se reduzem a uma única execução seguinte.

```ts title="Assinatura"
function watch(
  input: WatchInput,
  deps?: WatchDeps,
): Promise<WatchController>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against, and where each run's lock-file, translation memory, and run-status file live. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict every run of the session to a subset of the configured target locales. Validated once when watching starts, so an unconfigured locale throws `UNKNOWN_LOCALE` before any watching begins rather than failing on each run. An explicit empty array selects no locale at all. |
| `debounceMs` | `number` | no | How long to coalesce rapid source changes before running. Defaults to 300 milliseconds. |
| `onRun` | `(result: WatchRunResult) => void` | yes | Called after every run with its outcome. This is the only way to observe a watch session, since watch itself resolves as soon as watching starts. |
| `onReady` | `(() => void)` | no | Called once when the session's startup checks have passed and the watcher is attached, right before the initial run starts, so a caller can announce the session ahead of that run's output. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock, never for one this process holds. |
| `onProgress` | `ProgressListener` | no | Called as each run plans, sends and writes its locales, and as the watcher detects a change or goes idle, for progress reporting. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock, before any provider call, before that locale fails with `LOCK_CONTENDED` on the run's summary. Defaults to ten minutes. The lock-file guard a locale takes to record its result after writing its target file always allows the ten-minute default instead. |
| `concurrency` | `number` | no | How many locales to run at once. Defaults to 1. Validated once when watching starts, and applied to every run. |
| `cache` | `boolean` | no | Consult and update the translation memory, fuzzy reuse included. Defaults to true. |

**Retorna:** `WatchController`

**Lança:** [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#unknown_locale), [`LOCALE_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_unsupported_by_provider), [`CONCURRENCY_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#concurrency_invalid), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#lock_timeout_invalid), [`CONCURRENCY_BUDGET_CONFLICT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#concurrency_budget_conflict), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_unreadable), [`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#network_policy_violation), [`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#provider_construction_failed), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#config_invalid)

**Exemplo:** [Observar em um processo de longa duração](https://verbatra.kreitz-webdev.de/pt-BR/docs/programmatic-api.md#observar-em-um-processo-de-longa-duração)

O `debounceMs` tem padrão 300. O `onRun` é chamado uma vez por execução com um `WatchRunResult`: `{ status: "succeeded", summary }` ou `{ status: "failed", error: { code, message, causeCode?, hint? } }`, em que `causeCode` nomeia o erro com código que a falha envolve e `hint` é o próximo passo que o `errorHint` fornece. O `onReady` é chamado uma vez, depois que as verificações de inicialização passam e logo antes da execução inicial, para que você possa anunciar a sessão antes da saída dessa execução. Se o `onReady` lançar um erro, o processo do `watch` é fechado e a Promise de `watch` é rejeitada com esse erro antes de qualquer execução começar. O SDK não faz nenhum log; o `onRun` é a única saída. `concurrency`, `cache`, `onProgress`, `onLockWait` e `lockAcquireTimeoutMs` são repassados a cada execução e se comportam exatamente como no `translate`. O `locales` restringe cada execução da sessão a esse subconjunto e é validado uma vez na inicialização, não a cada ciclo.

Retorna um `WatchController` com um único método, `stop()`, que fecha o processo do `watch` e aguarda a execução em andamento. Todo código da linha **Lança** é recusado na inicialização, antes de o processo do `watch` existir, então a Promise de `watch` é rejeitada em vez de retornar um controlador. Dois deles pesam mais em uma sessão do que em uma execução: um `concurrency` acima de 1 com uma configuração que define `maxTokens` sempre lança `CONCURRENCY_BUDGET_CONFLICT`, porque não existe um `watch` com simulação, e, com a 0.12.0 ou mais recente, um provedor que não pode ser instanciado, como um cuja variável da chave de API não está definida, lança `PROVIDER_CONSTRUCTION_FAILED` uma única vez em vez de fazer cada execução falhar. Toda falha depois da inicialização é exposta pelo `onRun` e a observação continua.

### releaseHeldLocks [#releaseheldlocks]

<AvailableFrom version="0.12.0" />

Exclui toda trava de escrita que o processo atual mantém, para um processo prestes a sair sem deixar suas execuções em andamento terminarem: a CLI a chama quando uma interrupção para o `translate` ou o `import`, e quando uma segunda interrupção força a parada do `watch`. As execuções que adquiriram essas travas perdem a proteção, então chame-a só imediatamente antes de o processo sair. Não recebe argumentos, e a Promise só é rejeitada, com um `AggregateError` que nomeia os caminhos das travas, quando uma trava mantida não pôde ser excluída, depois de tentar todas as travas. Uma trava que uma operação ainda em execução está adquirindo, ou tenta adquirir, enquanto a `releaseHeldLocks` está em execução, é recusada com `RUN_CANCELLED` e não deixa nenhum arquivo para trás; a `releaseHeldLocks` espera no máximo três segundos por uma aquisição dessas.

```ts title="Assinatura"
function releaseHeldLocks(): Promise<void>;
```

**Retorna:** `void`

Uma trava que sobrou mesmo assim, por um processo encerrado à força, não precisa dela: uma execução em espera na mesma máquina vê que o processo registrado não existe mais e recupera a trava por conta própria. Veja [A trava de escrita](https://verbatra.kreitz-webdev.de/pt-BR/docs/the-lock-file.md#a-trava-de-escrita).

## Pseudolocalização [#pseudolocalização]

### pseudolocalize [#pseudolocalize]

<AvailableFrom version="0.11.0" />

Gera um locale falso só a partir das strings de origem, de modo que cortes de layout e strings que nunca foram extraídas para tradução apareçam antes de existir qualquer chave de API. Todo valor é acentuado, expandido em cerca de um terço do seu comprimento traduzível e envolvido por marcadores de limite `[` e `]`, enquanto os placeholders ficam intocados em toda sintaxe que os adaptadores reconhecem, inclusive ramos de plural e de `select` do ICU, tags de marcação e sequências de escape. Não instancia nenhum provedor, não lê nenhuma chave de API e não faz nenhuma requisição de rede.

```ts title="Assinatura"
function pseudolocalize(
  input: PseudolocalizeInput,
  deps?: PseudolocalizeDeps,
): Promise<PseudolocalizeResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `mode` | `"accented" \| "bidi"` | no | The transform to apply. Defaults to `accented`. `bidi` wraps every word of translatable text in a right-to-left mark and override (`U+200F U+202E` before, `U+202C U+200F` after), so it renders right to left while the stored letters keep their order; placeholders, ICU syntax, markup, digits and punctuation stay outside the override, and nothing is accented or padded. |
| `locale` | `string` | no | The pseudolocale's BCP-47 code. Defaults to `en-XA` in `accented` mode and to `ar-XB` in `bidi` mode, a code that resolves to right-to-left text direction, so an application that derives its layout direction from the locale flips without further setup. In `bidi` mode an `i18next-json` plural keyed by suffix also gets every CLDR category the pseudolocale's language needs and the source lacks (for `ar-XB`, `_zero`, `_two`, `_few` and `_many`), filled from the source's `other` form, or its `one` or first non-blank form when `other` is missing or blank, so no count falls back to another language. It must not be the source locale or any configured target locale, compared case-insensitively, so a pseudolocale can never stand in for a real translation. |
| `out` | `string` | no | Directory the pseudolocale file is written under, relative to `cwd`. Defaults to `.verbatra-local/pseudo`, which `verbatra init` already adds to `.gitignore`. The configured `files.pattern` is expanded inside it, so the file keeps the layout the application expects. It must name a directory inside `cwd`: an absolute path, one that climbs out with `..`, and `cwd` itself are all refused, as is a directory under which the expanded pattern would place the pseudolocale file beside a configured locale file, so a generated pseudolocale never lands outside the project or beside the real translations where nothing ignores it. The same holds after symbolic links are resolved, so a linked directory cannot carry the file outside `cwd` or into the directory of a configured locale file. |

**Retorna:** `PseudolocalizeResult`

**Lança:** [`PSEUDO_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#pseudo_output_conflict), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_invalid), [`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#target_unwritable)

**Exemplo:** [Gerar um pseudolocale](https://verbatra.kreitz-webdev.de/pt-BR/docs/programmatic-api.md#gerar-um-pseudolocale)

Todo valor gerado é submetido à mesma barreira de integridade que uma tradução de provedor precisa passar. Um que não passaria é copiado da origem literalmente e nomeado em `copied`, em vez de gravado de forma quebrada, de modo que a entrada continua presente e continua sendo renderizada.

<AvailableFrom version="0.12.0" />

O `mode` escolhe a transformação de `PSEUDO_MODES`: `accented`, o padrão, ou `bidi`, que em vez disso envolve cada palavra do texto traduzível em uma marca de direção da direita para a esquerda e uma substituição de direção, deixa placeholders, sintaxe ICU, marcação, dígitos e pontuação fora dele e não acentua nada. No modo `bidi`, o `locale` tem padrão `ar-XB`, um código que resolve para a direção da direita para a esquerda; veja [`verbatra pseudo`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/pseudo.md) para saber como as regras de plural do árabe desse código se combinam com as formas de plural da sua origem.

O `locale` tem padrão `en-XA` e o `out` tem padrão `.verbatra-local/pseudo`, que o `verbatra init` já adiciona ao `.gitignore`; o `files.pattern` configurado é expandido dentro dele, então o arquivo mantém o layout que o aplicativo espera. Um pseudolocale que nomeia um locale configurado, ou que cairia em um arquivo de locale configurado, é recusado com `PSEUDO_OUTPUT_CONFLICT` antes de qualquer leitura ou gravação, então não pode sobrescrever uma tradução real nem ocupar o lugar de uma; o mesmo vale para um `out` que é absoluto, sai de `cwd` ou nomeia o próprio `cwd`, como `.`, e, quando `deps.fs` implementa `realpath`, como o padrão faz, para um que, depois de resolvidos os links simbólicos, faz qualquer uma dessas coisas, cai no diretório de um arquivo de locale configurado ou cai em outro arquivo de que o projeto depende. Como o arquivo fica fora de `files.pattern`, o `translate` nunca gasta com ele e o `check` e o `diff` nunca o relatam como divergente.

Retorna um `PseudolocalizeResult`: o `locale`, o `mode`, o `path` absoluto, quantas `entries` foram processadas, quantas foram `transformed`, as chaves que foram `copied` e se algo foi `written`. A transformação é determinística, então uma segunda execução sobre uma origem inalterada não reescreve nada e informa `written` como falso. Para `xliff` e `apple-xcstrings`, cujos gravadores só aplicam alterações a um documento que já existe, a saída é copiada de novo da origem a cada gravação, então uma chave adicionada à origem depois da primeira execução ainda chega ao pseudolocale, e um XLIFF copiado tem o `target-language` reescrito para o pseudolocale.

## Catálogos tipados [#catálogos-tipados]

### generateTypes [#generatetypes]

<AvailableFrom version="0.11.0" />

Declara o catálogo de origem de um projeto como TypeScript: uma união de todas as chaves que ele contém e, por chave, os argumentos que a mensagem interpola. Tipe uma função de tradução com base no resultado e uma chave escrita errada ou um argumento de interpolação ausente vira um erro de compilação em vez de uma falha de busca em tempo de execução. Não gasta nada: nenhum provedor é instanciado, nenhuma variável de ambiente de chave de API é lida e nenhuma requisição de rede é feita.

```ts title="Assinatura"
function generateTypes(
  input: GenerateTypesInput,
  deps?: GenerateTypesDeps,
): Promise<GenerateTypesResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` and the output path are resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `out` | `string` | no | Where to write the declaration, relative to `cwd`. Defaults to DEFAULT_TYPES_PATH. Refused with `TYPES_OUTPUT_CONFLICT`, before anything is read or written, when it names no file, is absolute, climbs out of `cwd`, does not end in `.ts`, `.mts` or `.cts`, or names a configured locale file, the lock file, the provenance file, the translation-memory cache, a file verbatra searches for its configuration, the GenerateTypesInput.configPath file, or the GenerateTypesInput.glossaryPath file. When the file-system port implements `realpath`, the same checks run again after symbolic links are resolved. Names are compared case-insensitively. A generating run also refuses to replace an existing file there unless that file begins with the header line verbatra writes, after any leading byte order mark and blank lines, and refuses one too large to verify. |
| `configPath` | `string` | no | The configuration file `config` was loaded from, absolute or relative to `cwd`. It is refused as the output path even when its name is not one verbatra searches for. |
| `glossaryPath` | `string` | no | The glossary file the config names, absolute or relative to `cwd`, normally the `path` of a file-backed LoadedConfig.glossary. It is refused as the output path. |
| `check` | `boolean` | no | Compare instead of writing. The run reports whether the file on disk matches what a fresh generation would produce and leaves every file untouched. |

**Retorna:** `GenerateTypesResult`

**Lança:** [`TYPES_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#types_output_conflict), [`TYPES_UNWRITABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#types_unwritable), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#source_invalid)

**Exemplo:** [Gerar um catálogo tipado](https://verbatra.kreitz-webdev.de/pt-BR/docs/programmatic-api.md#gerar-um-catálogo-tipado)

Ele lê um arquivo (o catálogo do locale de origem) e grava um arquivo (a declaração); um arquivo de locale de destino nunca é tocado. As chaves são exatamente o que o adaptador de formato já produziu, na ordem do documento, então duas execuções sobre um catálogo inalterado gravam bytes idênticos. Os argumentos vêm dos placeholders que o adaptador extraiu, exceto nos formatos de mensagem ICU (`next-intl-json` e `arb`), em que cada mensagem é lida com o mesmo parser ICU que o adaptador usa. Toda chave é emitida como um literal de string entre aspas, então uma chave com ponto, palavra reservada, dígito inicial, aspa, ou uma chave vazia, é declarada literalmente em vez de descartada ou dividida de novo, e uma chave que o adaptador relatou em `excludedLeafPaths` nunca é declarada.

O que ele se recusa a afirmar importa tanto quanto o que declara. Uma mensagem sem placeholders recebe um formato em que passar qualquer argumento é um erro de tipo; uma cujos placeholders nomeiam seus argumentos recebe um formato de objeto; uma cujos placeholders são numerados ou anônimos recebe uma tupla somente leitura. Um argumento ICU que só alguns ramos de `select` ou `plural` usam é declarado como membro opcional. Os tipos dos argumentos vêm apenas do que o catálogo registra: `number` para um argumento ICU `number`, `plural` ou `selectordinal` e para um formatador ou conversão numérica, `Date | number` para um argumento ICU `date` ou `time` e um formatador `datetime` do i18next, `string` para um argumento ICU `select` e uma conversão de string do printf, e um alias `string | number` em todo o resto, nunca um `any` permissivo. Uma interpolação sem escape do i18next (`{{- name}}`) é declarada pelo nome que vem depois do prefixo. Uma mensagem que o adaptador relatou como inválida, uma que parece nomear e numerar seus argumentos ao mesmo tempo e uma cujo índice de placeholder está fora do intervalo são declaradas com seus argumentos relatados em `unresolved`, em vez de declaradas em silêncio como se não recebessem nenhum. As formas de plural irmãs nunca são fundidas: cada uma é declarada separadamente, e as que o adaptador marcou como plural são listadas.

O `out` tem padrão `DEFAULT_TYPES_PATH` (`verbatra-types.d.ts`). Antes de qualquer leitura ou gravação, `TYPES_OUTPUT_CONFLICT` recusa um `out` que não nomeia nenhum arquivo (inclusive um que termina com um separador de caminho), é absoluto, sai de `cwd` com `..`, nomeia o próprio `cwd` (`.`) ou não termina em `.ts`, `.mts` ou `.cts`, e um que nomeia um arquivo de locale configurado, o arquivo de lock, o arquivo de procedência, o cache de memória de tradução, um arquivo em que o verbatra busca sua configuração, `configPath`, o arquivo de configuração de onde `config` foi carregado, ou `glossaryPath`, o arquivo de glossário que ele nomeia; os nomes são comparados sem diferenciar maiúsculas de minúsculas e, quando `deps.fs` implementa `realpath`, como o padrão faz, as mesmas verificações são executadas de novo no lugar onde o caminho cai depois de resolvidos os links simbólicos. Uma execução que gera o arquivo também se recusa, com o mesmo código, a substituir um arquivo existente que não começa com a linha de cabeçalho que o verbatra grava, e deixa esse arquivo intocado. A lista completa está na página [`verbatra types`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/types.md). Com `check` definido, nada é gravado, nada é recusado pelo conteúdo, e a execução só informa se o arquivo versionado ainda confere, que é o formato de que uma barreira de CI precisa.

Retorna um `GenerateTypesResult`: o `path` absoluto, o `sourcePath` a partir do qual foi montado, quantas `keys` foram declaradas e quantas delas recebem pelo menos um argumento que o verbatra conseguiu determinar (`withArguments`, que nunca conta uma chave `unresolved`), as chaves `unresolved` e as `excluded` e `plural`, se algo foi `written`, se o arquivo no disco estava `stale` quando a execução começou, se estava `missing` por completo (um arquivo ausente também é `stale`) e se esta foi uma execução `check`.
