---
title: "Transmission et échange"
description: "Les points d'entrée du SDK pour importer et exporter classeurs et TMX, plus les instantanés de fichiers de locale et les chemins que verbatra résout par locale."
type: "reference"
---
# Transmission et échange
Les points d'entrée du SDK pour importer et exporter classeurs et TMX, plus les instantanés de fichiers de locale et les chemins que verbatra résout par locale.
## Instantanés de fichiers de locale [#instantanés-de-fichiers-de-locale]
Les briques d'un observateur à rafraîchissement en direct comme celui de Studio : capture l'état d'un fichier de locale, puis compte ce qui a changé depuis.
### readLocaleFileSnapshot [#readlocalefilesnapshot]
Lit un fichier de locale (la locale source ou n'importe quelle locale cible) et le réduit à un hash de contenu par clé. Un fichier qui n'existe pas encore se lit comme un instantané vide plutôt que de lever.
```ts title="Signature"
function readLocaleFileSnapshot(
input: ReadLocaleFileSnapshotInput,
deps?: ReadLocaleFileSnapshotDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `locale` | `string` | yes | The locale file to snapshot. Unlike most entry points this is not checked against the configured target locales, so the source locale can be snapshotted too. |
| `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. |
**Renvoie :** `LocaleFileSnapshot`
**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision)
Renvoie `{ locale, hashes }`.
### diffLocaleSnapshots [#difflocalesnapshots]
Compare deux instantanés du même fichier, pris à des moments différents, et compte les clés ajoutées, modifiées et supprimées entre les deux. Une fonction synchrone ordinaire : `diffLocaleSnapshots(previous, current)` renvoie `{ added, changed, removed }`. Des comptes seulement, jamais de noms de clés.
```ts title="Signature"
function diffLocaleSnapshots(
previous: LocaleFileSnapshot,
current: LocaleFileSnapshot,
): LocaleSnapshotDelta;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | `string` | yes | The locale this snapshot was taken for. |
| `hashes` | `ReadonlyMap` | yes | Content hash per key, in the order the adapter read them. |
**Renvoie :** `LocaleSnapshotDelta`
## Chemins de locale [#chemins-de-locale]
### createLocalePathResolver [#createlocalepathresolver]
Résout la correspondance entre locales et chemins du projet dans les deux sens, à partir de
`files.pattern`, des locales configurées et de `files.localeStyle`. `createLocalePathResolver(cwd,
config)` renvoie `{ pathFor, localeFor }` : `pathFor(locale)` est le chemin absolu du fichier d'une
locale, et `localeFor(path)` est la locale à laquelle appartient un chemin, ou `undefined` pour un
chemin qui n'appartient pas à ce projet, et toujours `undefined` pour un format à catalogue partagé comme `apple-xcstrings`. Tous les points d'entrée du SDK résolvent les chemins par
lui, donc un observateur ou un tableau de bord bâti sur le SDK voit exactement les chemins qu'une
exécution écrit.
```ts title="Signature"
function createLocalePathResolver(
cwd: string,
config: LocalePathResolverConfig,
): LocalePathResolver;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `sourceLocale` | `string` | yes | The source locale, which some styles spell differently from the targets. |
| `targetLocales` | `readonly string[]` | yes | Every target locale. All of them are mapped up front so collisions are caught immediately. |
| `format` | `FormatId` | yes | The configured format. Every format maps each locale to a distinct path except a shared-catalogue format (one holding every locale in a single file, such as `apple-xcstrings`), which maps every locale to the same path. A `custom:` format is always treated as one file per locale. Under the `posix` locale style, the `gettext-po` format also spells a script the gettext way (`sr-Latn` as `sr@latin`) rather than the ICU way (`sr_Latn`). |
| `files` | `object` | yes | The file layout. |
**Renvoie :** `LocalePathResolver`
**Lève :** [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision)
Toutes les vérifications ont lieu à la création du résolveur, avant toute lecture de fichier : un
pattern et un style incompatibles, ou une locale pour laquelle le style n'a pas d'écriture
correcte, lèvent `LOCALE_LAYOUT_INVALID`, et deux locales qui résolvent vers le même chemin lèvent
`LOCALE_PATH_COLLISION`.
## La paire classeur [#la-paire-classeur]
La remise pour les traducteurs humains, sous forme de classeur Excel ou de texte délimité ; voir [Traduction humaine](https://verbatra.kreitz-webdev.de/fr/docs/manual-translation.md).
### exportWorkbook [#exportworkbook]
Écrit les chaînes encore à traduire (clés manquantes et modifiées par locale ; ajoute les inchangées avec `includeUnchanged`) dans un classeur `.xlsx` stylisé. Les lignes portent le même signal de relecture que calcule une exécution translate. Aucun appel de fournisseur, aucune écriture du verrou.
```ts title="Signature"
function exportWorkbook(
input: ExportWorkbookInput,
deps?: ExportWorkbookDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` and `out` 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 handoff. Defaults to DEFAULT_WORKBOOK_PATH for `xlsx` and to DEFAULT_DELIMITED_PATH for the delimited and XLIFF formats. Refused with `EXPORT_OUTPUT_CONFLICT`, before anything is read or written, when it resolves outside `cwd`, or when it or a file the export would write names a configured locale file, the lock file, the provenance file, the translation-memory cache, a file verbatra searches for its configuration, the ExportWorkbookInput.configPath file, or the ExportWorkbookInput.glossaryPath file. For `xlsx` it is also refused when it names no file (including one ending in a path separator) or names `cwd` itself; a delimited or XLIFF export may write into `cwd`. Names are compared case-insensitively, and, when the file-system port implements `realpath`, again after symbolic links are resolved, so a link cannot carry the handoff anywhere a plain path could not. |
| `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. |
| `locales` | `readonly string[]` | no | Restrict the export to these target locales. Defaults to every configured target locale. |
| `includeUnchanged` | `boolean` | no | Include keys that are already up to date, not just the missing and stale ones. Useful when a translator needs the surrounding context to translate consistently. Defaults to false. |
| `format` | `ExchangeFormat` | no | The handoff shape to write. Defaults to `xlsx`. |
**Renvoie :** `ExportWorkbookResult`
**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`EXPORT_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#export_output_conflict), [`EXPORT_UNWRITABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#export_unwritable)
**Exemple :** [L'aller-retour du classeur](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#laller-retour-du-classeur)
`format` vaut `xlsx` par défaut ; `csv` et `tsv` écrivent à la place un `.csv` ou `.tsv` par locale, donc `out` désigne pour eux un répertoire (créé s'il manque) et un chemin de fichier pour `xlsx`. `out` vaut par défaut `DEFAULT_WORKBOOK_PATH` (`verbatra-translations.xlsx`) ou, pour les formats délimités et XLIFF, `DEFAULT_DELIMITED_PATH` (`verbatra-translations`), tous deux exportés comme constantes. Les valeurs acceptées sont exportées comme `EXCHANGE_FORMATS` et la valeur par défaut comme `DEFAULT_EXCHANGE_FORMAT`, pour qu'un outil qui enveloppe le SDK puisse valider un argument de format sans coder la liste en dur. Renvoie `{ path, locales }` : le chemin absolu écrit et un compte de lignes par locale.
Avant toute lecture, `EXPORT_OUTPUT_CONFLICT` refuse un `out` qui tombe hors de `cwd`, et un `out` qui, lui-même ou par un fichier que l'export écrirait dedans, nomme un fichier de locale configuré, le fichier de verrouillage, le fichier de provenance, le cache de mémoire de traduction, un fichier que verbatra cherche pour sa configuration, le fichier `configPath` ou le fichier `glossaryPath`, sans tenir compte de la casse et, quand `deps.fs` implémente `realpath` comme la valeur par défaut, de nouveau une fois les liens symboliques résolus. Un chemin `xlsx` est aussi refusé quand il ne nomme aucun fichier (y compris un chemin terminé par un séparateur de chemin) ou qu'il nomme `cwd` lui-même ; un répertoire `csv`, `tsv` ou XLIFF peut être `cwd`. Une écriture qui échoue, parce que le répertoire n'est pas inscriptible, qu'un répertoire ou un fichier gêne ou que le disque est plein, lève `EXPORT_UNWRITABLE` avec le fichier et le code du système de fichiers dans le message, et l'erreur du système de fichiers comme `cause`.
`format: "xliff2"` et `format: "xliff12"` écrivent pour un outil de TAO un `.xlf` en XLIFF 2.0 ou 1.2 par locale dans le répertoire `out` : une unité par clé, les espaces réservés et le balisage comme codes en ligne `` protégés, la description et le sens de la clé comme notes, le hash de la source dans les métadonnées de l'unité et un état de segment tiré de l'état de verrouillage et de relecture (`initial` pour une clé manquante ou obsolète, `translated` quand elle est à jour, `reviewed` quand elle est approuvée). Les deux types sont exportés, `XliffFormat` nommant les deux membres XLIFF d'`ExchangeFormat`. Voir [Confier à une agence de traduction](https://verbatra.kreitz-webdev.de/fr/docs/translation-agency.md).
Chaque unité qui a une cible porte aussi son origine : XLIFF 1.2 qualifie une cible de classe machine non approuvée avec `state-qualifier="mt-suggestion"`, et XLIFF 2.0 ajoute les entrées `origin` et `review-state` au groupe de métadonnées `verbatra` de l'unité. Le résultat porte alors aussi `provenanceMarkers` : `"written"`, ou `"unavailable"` quand le fichier de provenance n'a pas pu être lu et qu'aucun marqueur n'a été écrit. Voir [Preuves de traduction automatique](https://verbatra.kreitz-webdev.de/fr/docs/provenance-evidence.md#marqueurs-dans-les-exports).
### importWorkbook [#importworkbook]
Relit un classeur rempli dans les fichiers de locale, en exécutant les mêmes contrôles de dérive de source et d'intégrité que `translate`. Seules les lignes acceptées font avancer leur ligne de base du verrou ; une ligne vide ou rejetée continue de se réexporter jusqu'à sa vraie résolution.
```ts title="Signature"
function importWorkbook(
input: ImportWorkbookInput,
deps?: ImportWorkbookDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `workbook` | `string` | yes | Path to the filled handoff. For a delimited or XLIFF import the path is tried as a single file first, so one individual `.` file can be imported on its own, with the locale taken from its file name. A single XLIFF file whose name is not a configured target locale is matched by the target language it declares instead. If no file exists there, the path is treated as the directory the per-locale files were written into and every configured target locale found inside is read. |
| `cwd` | `string` | no | Directory the `files.pattern` and `workbook` 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. |
| `dryRun` | `boolean` | no | Read and validate the handoff but write nothing. The returned RunSummary reports what would have been applied, which is the safe way to inspect a handoff before trusting it. Defaults to false. |
| `format` | `ExchangeFormat` | no | The handoff shape to read. Defaults to the shape the extension of ImportWorkbookInput.workbook names: `csv` for `.csv`, `tsv` for `.tsv`, `xliff2` for `.xlf` or `.xliff`, and `xlsx` for `.xlsx` or any other file. For a directory it is the format of the export manifest inside, else of the `` files inside; a directory holding two formats, or none, is refused. `xliff2` and `xliff12` both read either XLIFF version, which is taken from the file. |
| `reviewer` | `string` | no | Free text naming the reviewer, 1 to 64 characters with no control characters, recorded on each value an XLIFF handoff marks `reviewed` or `final` (1.2: `signed-off`, `final`, or `approved="yes"`). It is stored in the committed provenance file, so it is public. Other handoff formats carry no review state, so it is not used for them. |
| `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. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock before that locale fails with `LOCK_CONTENDED`. The wait happens before the locale file is written. 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. |
**Renvoie :** [`RunSummary`](https://verbatra.kreitz-webdev.de/fr/docs/sdk/run-summary.md)
**Lève :** [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_timeout_invalid), [`REVIEWER_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#reviewer_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#provenance_file_invalid)
**Exemple :** [L'aller-retour du classeur](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#laller-retour-du-classeur)
Avec `csv` ou `tsv`, `workbook` est soit un seul fichier d'échange, soit le répertoire qui en contient un par locale, et la locale vient du nom du fichier. Un fichier terminé par `.csv` ou `.tsv` est lu dans ce format quand `format` est omis, et un répertoire dans le format de son manifeste d'export ou de ses fichiers de locale. Renvoie la même forme `RunSummary` que `translate` (avec `needsReview` toujours vide, puisqu'aucun fournisseur n'intervient). Une feuille pour une locale qui n'est pas une cible configurée fait échouer cette locale avec `CONFIG_INVALID` comme donnée sur le résumé, pas comme exception.
`onLockWait` et `lockAcquireTimeoutMs` se comportent exactement comme pour `translate`. `lockAcquireTimeoutMs` borne l'attente du verrou d'écriture d'une locale, pris avant l'écriture du fichier de cette locale, et une locale encore bloquée ensuite échoue avec `LOCK_CONTENDED` sur son propre résumé pendant que les autres locales s'importent. L'enregistrement d'un fichier écrit dans le fichier de verrouillage accorde toujours l'attente par défaut de dix minutes. Un dry run ne prend aucun verrou, donc aucune des deux options ne s'y applique.
`integrityRefusals` de chaque locale nomme les lignes que la barrière d'intégrité a refusées, avec le motif et ses `details`, comme chaque branche ICU qui ne convient pas à la langue cible. Une ligne retenue parce que sa source a changé depuis l'export n'apparaît que dans `integrityMismatches`. `exportWorkbook` signale comme `icu-arms` dans ses colonnes de relecture une traduction actuelle aux branches incorrectes.
Avec `xliff2` ou `xliff12`, qui lisent chacun les deux versions, et par défaut pour un chemin `workbook` terminé par `.xlf` ou `.xliff`, chaque code en ligne est ramené à son texte exact avant les mêmes contrôles. Une cible égale à la valeur actuelle ne change rien, une unité dont l'id ne nomme aucune clé source apparaît dans `malformedRows`, et une unité à l'état `reviewed` ou `final` (1.2 : `signed-off`, `final` ou `approved="yes"`) est enregistrée comme approuvée dans le fichier de provenance, avec `reviewer` comme nom s'il est fourni (validé comme pour `approveEntry`, `REVIEWER_INVALID`), et signalée par l'avis `HANDOFF_REVIEWS_RECORDED`.
## La paire TMX [#la-paire-tmx]
`importTmx` et `exportTmx` font entrer et sortir la [mémoire de traduction](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md) en TMX,
le format d'échange que produisent et lisent les principales plateformes de traduction. Aucune des
deux ne construit un fournisseur, ne lit une clé d'API ni ne fait de requête réseau : chaque valeur
vient du fichier ou de la mémoire déjà présente sur le disque. Ce n'est pas la paire classeur dans un
autre format. La paire classeur remet à un traducteur humain une tranche par locale du delta en attente ;
cette paire déplace la mémoire entière sous la forme d'un seul fichier multilingue entre outils.
### importTmx [#importtmx]
Lit un fichier TMX dans la mémoire du projet.
```ts title="Signature"
function importTmx(
input: ImportTmxInput,
deps?: ImportTmxDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `file` | `string` | yes | Path to the TMX file, resolved against `cwd`. |
| `cwd` | `string` | no | Directory the file and the memory 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. |
| `dryRun` | `boolean` | no | Read and validate the file but write nothing. Defaults to false. |
| `overwrite` | `boolean` | no | Let an imported unit replace a translation the memory already holds for the same source and locale. Off by default, so the project's own memory wins a collision. |
| `locales` | `readonly string[]` | no | Subset of configured target locales to import. Defaults to all of them. |
**Renvoie :** `ImportTmxResult`
**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`MEMORY_UNWRITABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#memory_unwritable)
**Exemple :** [L'aller-retour TMX](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#laller-retour-tmx)
Rien du fichier n'est tenu pour fiable. Le XML est analysé sous le durcissement du paquet d'échange,
si bien qu'une déclaration d'entité, un sous-ensemble DTD interne, un fichier surdimensionné ou mal
formé est refusé par une erreur structurée `SOURCE_INVALID` plutôt qu'analysé. Quand le problème a
un emplacement dans le fichier, le message indique la ligne, la colonne et, à l'intérieur d'une
unité de traduction, son rang en comptant à partir de 1, et `tmxErrorLocation(error)` renvoie le
même emplacement sous forme de `TmxErrorLocation`, ou `undefined` pour toute autre erreur, si bien
que tu n'as jamais à caster l'erreur ni son `cause`. Une étiquette de langue est résolue vers une
locale configurée par une règle explicite : écriture exacte après mise en minuscules et conversion
des tirets bas en traits d'union ; à défaut, la plus longue locale configurée qui est un préfixe de
sous-étiquettes de l'étiquette (recherche de la RFC 4647), ou sinon une locale configurée qui ne
prolonge l'étiquette que par des sous-étiquettes de région ou de variante, jamais par une
sous-étiquette d'écriture, si bien que deux étiquettes aux sous-étiquettes d'écriture ou de région
différentes (`sr-Latn` et `sr-Cyrl`, `de-AT` et `de-CH`) ne correspondent jamais ; et une étiquette n'est signalée comme ambiguë que lorsque les
locales qu'elle pourrait atteindre ne se trouvent pas sur une même chaîne de préfixes. Les segments
d'une unité qui se résolvent vers la même locale, locale source comprise, ne laissent jamais le
dernier l'emporter : une étiquette exacte l'emporte sur une correspondance par préfixe, et deux
segments de même rang aux valeurs différentes ne stockent rien pour cette locale et sont comptés
comme `conflicting` (pour la locale source, l'unité est refusée et comptée dans
`conflictingSourceUnits`). Chaque traduction candidate passe ensuite la même barrière d'intégrité
sur les placeholders, le balisage en ligne, l'ICU, la dégénérescence et la vacuité que subissent
déjà la sortie du fournisseur et une ligne de classeur remplie, vérifiée à l'entrée de
l'enregistrement dans la mémoire plutôt que laissée à l'exécution qui la lira plus tard.
Quand une unité importée contredit une traduction que la mémoire possède déjà, la mémoire l'emporte,
sauf si `overwrite` est passé. Les unités sont stockées sous l'empreinte de configuration actuelle,
la même clé qu'écrit une exécution réelle, et cessent donc de correspondre dès que le fournisseur, le
modèle, le ton, les termes du glossaire que verbatra enverrait ou la `localeMap` du fournisseur changent. Importer deux fois le même fichier ne change rien la seconde
fois.
Face à des données abîmées, renvoie un rapport au lieu de lever : combien d'unités ont été lues, un
décompte par locale de `added`, `unchanged`, `overwritten`, `kept`, `duplicates`, `conflicting` et
`rejected` par motif, plus les unités ignorées, sans segment source, ayant perdu leur balisage en
ligne ou dont le texte `sub` a été laissé de côté (`subflowDroppedUnits`), et les étiquettes de
langue sans correspondance ou à correspondance ambiguë. `memoryWritable` vaut false quand le fichier
de mémoire a été écrit par un verbatra plus récent, auquel cas il est laissé intact. Les décomptes
par locale sont tout de même renvoyés, comme lors d'une exécution à blanc, donc `added` et
`overwritten` décrivent ce qui serait entré ; avec `memoryWritable` à false, rien n'est entré.
Chaque locale liste aussi ses `refusals`, un `TmxUnitRefusal` par unité comptée sous un motif de la
barrière : `{ unit, reason, details? }`, où `unit` est la position de l'unité dans le fichier, à
partir de 1, et `details` nomme ce qui ne va pas, comme chaque branche ICU qui ne convient pas à la
langue cible.
### tmxErrorLocation [#tmxerrorlocation]
Lit, à partir de ce que `importTmx` a levé, où un fichier TMX refusé a échoué. Renvoie une
`TmxErrorLocation` (`{ line, column, unit? }`, le tout en comptant à partir de 1) pour un refus
`SOURCE_INVALID` qui a un emplacement dans le fichier, et `undefined` pour toute autre erreur, y
compris un fichier absent ou surdimensionné, si bien que tu n'as jamais à caster l'erreur ni son
`cause`.
```ts title="Signature"
function tmxErrorLocation(
error: unknown,
): TmxErrorLocation | undefined;
```
**Renvoie :** `TmxErrorLocation | undefined`
```ts title="Exemple"
import { importTmx, tmxErrorLocation, type VerbatraConfig } from "@verbatra/sdk";
declare const config: VerbatraConfig;
try {
await importTmx({ config, file: "legacy.tmx" });
} catch (error) {
const at = tmxErrorLocation(error);
if (at !== undefined) console.error(`line ${at.line}, column ${at.column}`);
}
```
### exportTmx [#exporttmx]
Écrit la mémoire en TMX 1.4b. `out` vaut par défaut `DEFAULT_TMX_PATH` (`verbatra-memory.tmx`), exporté comme
constante. Avant toute lecture de la mémoire, `TMX_OUTPUT_CONFLICT` refuse un `out` qui ne nomme
aucun fichier (y compris un `out` terminé par un séparateur de chemin), qui tombe hors de `cwd` ou
sur `cwd` lui-même, ou qui nomme un fichier de locale configuré, le fichier de verrouillage, le
cache de mémoire de traduction, un fichier que verbatra cherche pour sa configuration, le fichier
`configPath` ou le fichier `glossaryPath`, sans tenir compte de la casse et, quand `deps.fs`
implémente `realpath` comme la valeur par défaut, de nouveau une fois les liens symboliques résolus.
Une écriture qui échoue, parce que le répertoire n'est pas inscriptible, qu'un répertoire occupe
déjà ce chemin ou que le disque est plein, lève `TMX_UNWRITABLE` avec le fichier et le code du
système de fichiers dans le message. Seules les entrées sous l'empreinte de configuration actuelle
sont écrites, c'est-à-dire l'ensemble qu'une exécution réutiliserait. Les étiquettes de langue sont
écrites sous forme BCP 47 (`en_US` devient `en-US`), ce qui ne change pas l'indexation de la
mémoire. Une mémoire vide produit un fichier valide et vide, pas une erreur.
```ts title="Signature"
function exportTmx(
input: ExportTmxInput,
deps?: ExportTmxDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `out` | `string` | no | Where to write the file. Defaults to DEFAULT_TMX_PATH, resolved against `cwd`. Refused with `TMX_OUTPUT_CONFLICT`, before anything is read or written, when it names no file, resolves outside `cwd` or to `cwd` itself, or names a configured locale file, the lock file, the translation-memory cache, a file verbatra searches for its configuration, the ExportTmxInput.configPath file, or the ExportTmxInput.glossaryPath file. Names are compared case-insensitively, and, when the file-system port implements `realpath`, again after symbolic links are resolved, so a link cannot carry the file anywhere a plain path could not. |
| `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. |
| `cwd` | `string` | no | Directory the output path and the memory 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. |
| `locales` | `readonly string[]` | no | Subset of configured target locales to export. Defaults to all of them. |
| `toolVersion` | `string` | no | Value for the TMX header's `creationtoolversion`. Defaults to `unknown`. |
**Renvoie :** `ExportTmxResult`
**Lève :** [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_invalid), [`TMX_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#tmx_output_conflict), [`TMX_UNWRITABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#tmx_unwritable), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision)
**Exemple :** [L'aller-retour TMX](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#laller-retour-tmx)
Renvoie `{ path, units, locales, withoutSource, illegalCharactersRemoved, provenanceMarkers }` ; `withoutSource` compte les entrées laissées de côté parce que la mémoire n'a pas de texte source pour elles, ce qui n'arrive qu'aux entrées héritées d'un cache écrit avant que la mémoire ne stocke le texte source, et `illegalCharactersRemoved` compte les caractères que XML 1.0 ne peut pas représenter et qui ont été retirés du texte des segments.
Chaque segment cible porte `` (`machine`, `human`, `import` ou `unknown`,
le type `TmxOrigin`) et un segment `machine` aussi `` (`approved`,
`unreviewed` ou `rejected`, le type `TmxReview`), déduits de chaque clé dont l'entrée de
verrouillage nomme la source du segment et dont l'enregistrement décrit exactement son texte.
`provenanceMarkers` vaut `"unavailable"` quand le fichier de provenance ou le fichier de
verrouillage n'a pas pu être lu ; dans ce cas, aucun segment ne porte de propriété.