---
title: "verbatra export"
description: "Exporta as strings sem tradução em uma entrega: pasta de trabalho do Excel, um CSV ou TSV por locale, ou um XLIFF por locale para uma ferramenta CAT."
type: "reference"
---
# verbatra export

Exporta as strings sem tradução em uma entrega: pasta de trabalho do Excel, um CSV ou TSV por locale, ou um XLIFF por locale para uma ferramenta CAT.

Grava as strings que precisam de tradução em uma entrega que uma pessoa preenche e devolve ao [`verbatra import`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/import.md). Por padrão, ela leva só as strings ausentes e alteradas, as mesmas chaves que uma execução automática enviaria a um provedor. Uma chave cujo valor de origem está vazio ou só tem espaços não recebe linha até você escrever o texto de origem dela. O `export` nunca chama um provedor e não precisa de chave de API.

## Sinopse [#sinopse]

```bash
verbatra export [flags]
```

## Exemplos [#exemplos]

```bash
# write the workbook with missing and changed strings
verbatra export

# only the German and French sheets, to a specific path
verbatra export --locales de,fr --out handoff/round-2.xlsx

# one de.csv and fr.csv under handoff/
verbatra export --format csv --out handoff

# one de.xlf and fr.xlf in XLIFF 2.0 for a CAT tool
verbatra export --format xliff2 --out handoff
```

## Flags [#flags]

| Flag | Argumento | Padrão | Efeito |
| --- | --- | --- | --- |
| `--out` | `<path>` | `verbatra-translations.xlsx`, ou `verbatra-translations` para os outros formatos | onde gravar a entrega: um arquivo para `xlsx`, um diretório para `csv`, `tsv`, `xliff2` e `xliff12` |
| `--format` | `<format>` | `xlsx` | `xlsx` (pasta de trabalho do Excel), `csv` ou `tsv` (um arquivo por locale), `xliff2` ou `xliff12` (um arquivo XLIFF por locale) |
| `--locales` | `<list>` | todos os locales de destino configurados | exporta só este subconjunto separado por vírgulas; um locale não configurado falha com `UNKNOWN_LOCALE` e uma lista vazia com `INVALID_LOCALES`, ambos com saída `2` |
| `--include-unchanged` | nenhum | desativado | exporta também as strings que já estão atualizadas |

Aceita também as [flags globais](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli.md#flags-globais) `--cwd`, `--config` e `--json`.

## Comportamento [#comportamento]

### CSV e TSV [#csv-e-tsv]

`--format csv` e `--format tsv` gravam um `<locale>.csv` ou `<locale>.tsv` por locale exportado, com as mesmas colunas, na mesma ordem, que uma planilha da pasta de trabalho. `--out` nomeia o diretório, que é criado se não existir.

Um arquivo delimitado pode ser comparado com diff e abre em qualquer lugar, mas não tem proteção de células: todas as colunas são editáveis e a coluna `Source hash` fica visível. Um hash editado nunca é aceito: a importação o compara com a origem atual e retém a linha.

Cada exportação delimitada também grava um manifesto oculto, `.verbatra-export-csv.json` ou `.verbatra-export-tsv.json`, que nomeia os locales gravados. Uma exportação posterior com `--locales` mais restrito aposenta os locales que saíram: os arquivos deles permanecem em disco, e o [`verbatra import`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/import.md) os recusa como sobras. A exportação nunca exclui nada do diretório de saída.

### XLIFF [#xliff]

<AvailableFrom version="0.12.0" />

`--format xliff2` grava XLIFF 2.0 e `--format xliff12` grava XLIFF 1.2: um `<locale>.xlf` por locale exportado no diretório de `--out`, mais um manifesto `.verbatra-export-xliff.json` que funciona como o do CSV. Cada chave vira uma unidade com o nome da chave, placeholders e marcação viram códigos inline protegidos, a descrição e o significado da chave viram notas, e o estado do segmento segue o estado no arquivo de lock e o estado de revisão (`initial` para uma chave ausente ou obsoleta, `translated` quando está atualizada, `reviewed` quando foi aprovada). Veja [Entregar a uma agência (XLIFF)](https://verbatra.kreitz-webdev.de/pt-BR/docs/translation-agency.md).

Cada destino também diz de onde veio. No XLIFF 1.2, um destino que um provedor, a memória de tradução ou um agente de IA escreveu e que nenhuma pessoa aprovou traz `state-qualifier="mt-suggestion"`; no XLIFF 2.0, o grupo de metadados `verbatra` da unidade traz `origin` e `review-state`. A importação ignora os dois. Quando `verbatra.provenance.json` não pode ser lido, nenhum marcador é gravado e o resultado de `--json` traz `provenanceMarkers: "unavailable"`. Veja [Registrar evidências de tradução automática](https://verbatra.kreitz-webdev.de/pt-BR/docs/provenance-evidence.md#marcadores-nas-exportações).

### Onde a entrega é gravada [#onde-a-entrega-é-gravada]

A entrega só é gravada dentro da raiz do projeto. Antes de ler qualquer coisa, o `export` recusa com `EXPORT_OUTPUT_CONFLICT` um `--out` que saia da raiz do projeto ou que (por si mesmo ou por um arquivo que ele gravaria) nomeie um arquivo de que o projeto depende: um arquivo de locale configurado, o arquivo de lock, o arquivo de procedência, o cache da memória de tradução, um arquivo de configuração que o verbatra procura, a configuração que a execução carregou ou o arquivo de `glossary` configurado. Para `xlsx`, também são recusados um caminho que não nomeia nenhum arquivo (como `out/`) e a própria raiz do projeto. Os nomes são comparados sem diferenciar maiúsculas de minúsculas, e as verificações são repetidas depois que os links simbólicos são resolvidos.

Um caminho que passa ainda pode falhar na gravação (sem permissão de escrita, caminho já ocupado, disco cheio): a execução para com `EXPORT_UNWRITABLE`, nomeando o arquivo e o código do sistema de arquivos.

Um locale de destino que não consegue nomear sua planilha ou seu arquivo interrompe a exportação com `WORKBOOK_INVALID`. O nome de uma planilha xlsx deve ter de 1 a 31 caracteres, não pode conter nenhum de `: \ / ? * [ ]` e não pode coincidir com `Instructions` nem com o nome da planilha de outro locale de destino, sem diferenciar maiúsculas de minúsculas. O nome de um arquivo `csv`, `tsv` ou `xlf` não pode ser vazio, `.` ou `..`, e não pode conter separador de caminho, caractere de controle nem nenhum de `: * ? " < > |`. O mesmo código cobre uma pasta de trabalho que não pôde ser serializada.

### Retorno no terminal [#retorno-no-terminal]

<AvailableFrom version="0.12.0" />

O `export` mostra uma linha enquanto grava e, quando havia algo a entregar, nomeia a importação que traz o arquivo preenchido de volta:

```text output
verbatra: exporting to xlsx... done (0.3s)
next: verbatra import verbatra-translations.xlsx (once your translators have filled it in)
```

Quando nada está pendente e `--include-unchanged` não foi passado, o arquivo não tem linhas, e a linha `next:` sugere a mesma exportação com `--include-unchanged`, mantendo `--format`, `--out`, `--locales`, `--cwd` e `--config`. <AvailableFrom version="0.13.5" />

Essas linhas vão para o stderr, e `--quiet` as omite. Veja [Saída no terminal](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#saída-no-terminal).

Um `verbatra.limits.json` que não pode ser usado é ignorado com um alerta no stderr (`LIMITS_FILE_IGNORED` no `--json`).

### Saída JSON [#saída-json]

Schema: [`export-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/export-envelope.json) valida o envelope inteiro (o objeto JSON da resposta); [Schemas](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#schemas) lista os outros.

Com `--json`, o [envelope](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#saída-json) traz para onde a entrega foi e a contagem de linhas por locale:

```ts
{
  path: string;                // absolute path: the workbook for xlsx, the output directory otherwise
  locales: { locale: string; rows: number }[];
  provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only
  limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string };
}
```

## Códigos de saída [#códigos-de-saída]

| Código | Significado |
| --- | --- |
| `0` | a entrega foi gravada |
| `2` | não foi possível executar: um erro que afeta a execução inteira, um caminho de saída recusado (`EXPORT_OUTPUT_CONFLICT`), uma entrega que não pôde ser gravada (`EXPORT_UNWRITABLE`, `WORKBOOK_INVALID`) ou um erro de uso |

O `export` não tem modo de falha por locale, então nunca termina com `1`. Veja [Códigos de saída](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#códigos-de-saída) para o contrato que todo comando segue.

## Veja também [#veja-também]

- [Tradução manual](https://verbatra.kreitz-webdev.de/pt-BR/docs/manual-translation.md) cobre o layout da pasta de trabalho, as colunas de revisão e o ciclo de ida e volta completo.
- [Entregar a uma agência (XLIFF)](https://verbatra.kreitz-webdev.de/pt-BR/docs/translation-agency.md) cobre a entrega em XLIFF para uma ferramenta CAT.
- [`verbatra import`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/import.md) lê de volta a entrega preenchida.
