Docs / Démarrer
Page traduite automatiquement
Démarrage rapide du SDK
Installe @verbatra/sdk, prévisualise une exécution sans clé d'API, traduis depuis ton propre script, gère les erreurs et protège ta CI.
À la fin de cette page, un script TypeScript à toi traduit un fichier de locale anglais en allemand, rapporte ce qui s'est passé et fait échouer un job CI quand une locale n'est plus synchronisée. Il te faut Node.js ^22.18.0 || >=24 et une dizaine de minutes. Les trois premières étapes ne demandent aucune clé d'API.
Chaque étape est un script complet que tu lances avec node. Node.js exécute directement les fichiers TypeScript, sans option supplémentaire. Les scripts utilisent import et un await de premier niveau : la première étape marque donc aussi le projet comme module ES.
Étapes
Installe le SDK
npm init -y
npm pkg set type=module
npm install --save-dev @verbatra/sdkLance ça dans un répertoire vide : npm init -y crée le package.json que npm pkg set type=module marque comme module ES. Dans un projet existant, saute npm init -y. Si pnpm s'arrête avec ERR_, consulte Installation.
Ajoute un fichier source et une config
{
"greeting": "Hello, {{name}}!",
"cart": {
"empty": "Your cart is empty."
}
}import { defineConfig } from "@verbatra/sdk";
export default defineConfig({
sourceLocale: "en",
targetLocales: ["de"],
format: "i18next-json",
files: { pattern: "locales/{locale}.json" },
provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
});loadConfig trouve ce fichier à partir du répertoire de travail et le valide. Choisis ta stack donne le format de ton framework, et Fournisseurs liste chaque fournisseur et ses options. Pour te passer complètement du fichier, passe le même objet en configOverride ; voir Recettes SDK.
Prévisualise l'exécution sans clé
import { loadConfig, translate } from "@verbatra/sdk";
const config = await loadConfig();
const preview = await translate({ config, dryRun: true });
for (const locale of preview.locales) {
console.log(`${locale.locale}: would translate ${locale.translated.join(", ")}`);
}node preview.tsde: would translate cart.empty, greetingUne exécution à blanc ne construit aucun fournisseur : elle ne demande donc aucune clé, ne dépense rien et n'écrit rien. Passe plutôt estimate: true pour obtenir un chiffre en tokens ou en coût ; voir Estimer le coût.
Traduis et lis le résumé
import { loadConfig, translate } from "@verbatra/sdk";
const config = await loadConfig();
const summary = await translate({
config,
onProgress: (event) => {
if (event.type === "locale-finished") console.log(`${event.locale}: ${event.translated} keys`);
},
});
const { succeeded, partial, failed, usage } = summary;
console.log(`${succeeded.length} ok, ${partial.length} partial, ${failed.length} failed`);
if (usage !== undefined) {
console.log(`tokens: ${usage.inputTokens} in, ${usage.outputTokens} out`);
}
for (const locale of summary.locales) {
if (locale.status === "failed") {
console.error(`${locale.locale}: ${locale.error?.code} ${locale.error?.message}`);
continue;
}
for (const entry of locale.needsReview) {
console.warn(`review ${locale.locale}/${entry.key}: ${entry.reasons.join(", ")}`);
}
}
if (failed.length > 0 || partial.length > 0) {
process.exitCode = 1;
}Le fournisseur lit sa clé dans l'environnement, et contrairement à la CLI, le SDK ne charge pas les fichiers .env : transmets-la toi-même. Fournisseurs nomme la variable de chaque fournisseur.
node --env-file=.env translate.tslocales/de.json contient maintenant les deux clés, avec {{name}} intact. Une locale partial a été écrite avec des clés encore manquantes, donc le script échoue dessus comme sur failed. Les problèmes par locale arrivent comme des données sur le résumé ; seul un problème touchant toute l'exécution lève une erreur. translate liste toutes les autres options.
Gère les erreurs Disponible à partir de 0.12.0
Un problème touchant toute l'exécution lève une SdkError. Décide de la suite selon son code stable, et affiche errorHint pour connaître l'étape suivante.
import { errorHint, loadConfig, SdkError, translate } from "@verbatra/sdk";
try {
const summary = await translate({ config: await loadConfig() });
console.log(`${summary.succeeded.length} locales translated`);
} catch (error) {
if (!(error instanceof SdkError)) {
throw error;
}
switch (error.code) {
case "CONFIG_NOT_FOUND":
console.error(`${error.code}: ${error.message} (searched from ${process.cwd()} upward)`);
break;
case "PROVIDER_CONSTRUCTION_FAILED":
console.error(`${error.code}: the provider could not be built, most often for a missing key`);
break;
default:
console.error(`${error.code}: ${error.message}`);
}
const hint = errorHint(error);
if (hint !== undefined) {
console.error(`next: ${hint}`);
}
process.exitCode = 2;
}Lance-le sans la clé : il signale PROVIDER_ en nommant la variable manquante, jamais une valeur de clé. Codes d'erreur liste chaque code.
Protège ta CI avec check
import { check, loadConfig } from "@verbatra/sdk";
const summary = await check({ config: await loadConfig() });
for (const locale of summary.locales) {
console.log(`${locale.locale}: ${locale.missing} missing, ${locale.stale} stale`);
}
if (!summary.inSync) {
process.exitCode = 1;
}node check.tscheck n'appelle aucun fournisseur et n'écrit rien : il ne demande donc aucune clé en CI. Le script sort avec 1 quand une chaîne source n'a pas de traduction ou a changé depuis sa traduction.
CommonJS
Dans un projet CommonJS, require("@verbatra/sdk") renvoie les mêmes exports. Le await de premier niveau n'y est pas disponible, donc enveloppe les appels dans une fonction async.
Étapes suivantes
- Recettes SDK : estimations, mode surveillance, une doublure de test pour le fournisseur, la file de relecture, et les allers-retours classeur et TMX.
- Référence SDK : chaque point d'entrée, son entrée et ce qu'il lève.
- Fournisseurs personnalisés et adaptateurs de format personnalisés : branche ce que verbatra ne fournit pas.
- Sûreté de la traduction : ce que verbatra vérifie avant d'écrire une traduction.