Автоматизируйте локализацию файлов с помощью API
Загрузите исходный файл, запустите задание перевода документа и скачайте переводы в отдельную папку.
Используйте API для работы с документами, если ваш бэкенд управляет файлами и должен координировать перевод с работой своего хранилища. В этом примере файл messages/en.json переводится на немецкий и французский. CLI выполняет те же операции с файлами в локальном проекте.
Вам понадобятся Node.js 22 или новее, организация, движок с настроенной моделью и ключ API с доступом к переводу. Для первого запуска настройте перевод без ручной проверки. Добавьте проверку, когда отладите весь цикл работы с файлом.
Подготовьте исходный файл #
Создайте messages/en.json:
{
"title": "Account settings",
"save": "Save changes"
}Задайте свои значения для следующих переменных окружения:
export LINGO_API_KEY="YOUR_API_KEY"
export LINGO_ORGANIZATION_ID="YOUR_ORGANIZATION_ID"
export LINGO_ENGINE_ID="YOUR_ENGINE_ID"
export LINGO_REQUEST_ID="account-settings-v1-de-fr"При повторных попытках с тем же исходным файлом и конфигурацией используйте тот же ИД запроса. При отправке новой версии меняйте его.
Загрузите файл, запустите задание и получите результаты #
Сохраните эту программу как translate-file.mjs:
import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";
const origin = "https://api.lingo.dev";
const {
LINGO_API_KEY: apiKey,
LINGO_ORGANIZATION_ID: orgId,
LINGO_ENGINE_ID: engineId,
LINGO_REQUEST_ID: requestId,
} = process.env;
if (!apiKey || !orgId || !engineId || !requestId) throw new Error("Set the four LINGO environment variables");
async function request(path, options = {}) {
const response = await fetch(new URL(path, origin), {
...options,
headers: { "X-API-Key": apiKey, ...options.headers },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
return response;
}
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");
let job = await (
await request(`/v2/organizations/${encodeURIComponent(orgId)}/localization/jobs`, {
method: "POST",
headers: { "Content-Type": "application/json", "Idempotency-Key": requestId },
body: JSON.stringify({
engineId,
sourceLocale: "en",
targetLocales: ["de", "fr"],
documents: [{ key: "messages/en.json", format: { type: "json" }, source: address }],
}),
})
).json();
await writeFile("file-job.json", JSON.stringify({ id: job.id, requestId, source: address }, null, 2));
for (const upload of job.uploads) {
await request(upload.uploadUrl, {
method: "PUT",
headers: { "Content-Type": "application/octet-stream" },
body: bytes,
});
}
job = await (
await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}/start`, {
method: "POST",
})
).json();
const deadline = Date.now() + 120_000;
while (["Pending", "Running"].includes(job.status._tag)) {
if (Date.now() >= deadline) throw new Error(`Keep job ${job.id} and check again later`);
await delay(2000);
job = await (await request(`/v2/localization/jobs/${encodeURIComponent(job.id)}`)).json();
}
await mkdir("translated", { recursive: true });
for (const { locale, status } of job.documents[0].targets) {
if (status._tag !== "Completed") {
throw new Error(`Inspect job ${job.id}: ${locale} is ${status._tag}`);
}
const output = await request(status.downloadUrl);
await writeFile(`translated/${locale}.json`, new Uint8Array(await output.arrayBuffer()));
console.log(`Saved translated/${locale}.json`);
}Запустите node translate-file.mjs, затем проверьте translated/de.json и translated/fr.json. В обоих файлах должны сохраниться исходные ключи, а текст должен быть на соответствующем языке. Программа сохраняет результаты отдельно от файлов приложения, чтобы вы могли проверить их перед заменой уже принятого контента.
Возобновите работу, не создавая дубликат задания #
file-job.json сохраняет ИД задания на сервере и хеш исходного файла. Если ответ на запрос загрузки или запуска потерян, получите это задание, загрузите оставшиеся артефакты и повторите запрос запуска. Повторный запрос создания с исходным ключом идемпотентности тоже вернёт то же задание.
Истечение времени ожидания при опросе не отменяет работу. Продолжайте запрашивать состояние задания по сохранённым данным. Не создавайте новое только потому, что локальная программа перестала ждать.
В этом примере программа останавливается при первом незавершённом переводе или неудачном запросе. Уже сохранённые файлы остаются в translated/. Чтобы продолжить, получите задание, записанное в file-job.json, и скачайте готовые переводы, используя их значения downloadUrl. См. статус и результаты задания. Если скачать файл не удалось, создавать новое задание перевода не нужно.
Добавьте инкрементальные обновления #
Для следующей версии передайте previousSource и previousTranslations вместе с новым адресом исходного файла. Сохраняйте байты каждого указанного артефакта до успешной загрузки. Включите принятые правки, сделанные вручную, в файлы предыдущих переводов, которые вы передаёте.
В разделе Как переводить документы описаны поля и правила повторного использования. Перед публикацией сравните версию исходного файла в задании с текущей версией и проверьте, не менялись ли переводы после отправки задания. Этап принятия результатов описан в разделе Как построить рабочий процесс перевода.