# General Translation Platform: Перевод файлов
URL: https://generaltranslation.com/ru/docs/platform/core/guides/translating-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Как загружать, переводить и скачивать файлы с помощью библиотеки generaltranslation.

Библиотека `generaltranslation` может переводить исходные файлы целиком. На этой странице описаны процессы загрузки файлов, постановки файла в очередь на перевод, проверки статуса и скачивания результата.

## Перед началом [#before-start]

Убедитесь, что вы прошли [Quickstart](/docs/platform/core/quickstart): установили `generaltranslation` и инициализировали класс [GT](/docs/platform/core/reference/gt-class/constructor).

## Как работает перевод файлов [#file-translation-works]

Перевод файлов выполняется в виде задач:

1. Загрузите исходный файл.
2. Поставьте файл в очередь на перевод.
3. Проверьте статус перевода.
4. Скачайте переведённый файл.

Для перевода файлов требуется несколько вызовов API, поскольку в проектах часто переводят много файлов. Разделение на отдельные шаги даёт больше гибкости при работе с API: так проще обрабатывать файлы пакетно, повторять неудачные операции, опрашивать задачи и скачивать результат, когда он будет готов.

При загрузке создаются записи об исходных файлах. Последующий вызов [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) может запустить по одной задаче для каждой пары «исходный файл — целевая локаль», которая ещё требует обработки. (Подробнее см. методы [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) и [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data)).

Для файлов SVG передавайте исходный XML в кодировке UTF-8 с `fileFormat: 'SVG'`. При переводе обновляются текстовые узлы, а фигуры и стили сохраняются. Асинхронный проход по разметке может заново отцентрировать текст и сократить слишком длинные переводы, сохраняя заданные размеры шрифта, поэтому дождитесь завершения обработки файла, прежде чем скачивать его. Некорректный XML отклоняется.

## 1. Загрузите исходный файл [#upload]

Для примера в этом руководстве мы переведём этот JSON-файл на английском языке:

```json
{
  "hello": "Hello",
  "world": "World"
}
```

Прочитайте файл, отформатируйте его содержимое, затем вызовите [uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files), чтобы загрузить файлы.

```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import type { FileUpload } from 'generaltranslation/types';

// (i) Читаем содержимое файла
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) Формируем объект с содержимым файла
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) Загружаем файл
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);
```

В ответе возвращается список ссылок на файлы. Это позволяет позже поставить файл в очередь на перевод, проверить статус файла и скачать переведённый файл.

```ts title="Output"
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    branchId: '123456789',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]
```

## 2. Поставьте файл в очередь на перевод [#enqueue]

Используйте [enqueueFiles](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files), указав ссылку на загруженный файл и целевые локали. В этом примере мы переведём файл на испанский (`es`).

```typescript title="src/index.ts"
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  branchId: uploadedFiles[0].branchId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};

const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
    sourceLocale: 'en',
    targetLocales: ['es'],
  }
);
```

В ответе возвращается результат с данными о задаче.

```ts title="Output"
{
  jobData: {
    'job-123456': {
      sourceFileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      targetLocale: 'es',
      projectId: 'your-project-id',
      force: false
    }
  },
  locales: ['es'],
  message: 'Successfully enqueued 1 file translation jobs in 1 batch(es)'
}
```

## 3. Проверьте статус файла [#status]

Используйте [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data), чтобы проверить, завершён ли перевод файла и готов ли файл к скачиванию.

```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];

const status = await gt.queryFileData({
  translatedFiles: [
    {
      fileId,
      versionId,
      branchId,
      locale: 'es',
    },
  ],
});
```

Если файл всё ещё переводится, `completedAt` равно `null`. После завершения в нём будет временная метка:

```ts title="Output"
{
  translatedFiles: [
    {
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      locale: 'es',
      completedAt: '2024-01-15T12:00:00Z'
    }
  ]
}
```

## 4. Скачайте переведённый файл [#download]

Наконец, скачайте переведённый файл с помощью метода [downloadFile](/docs/platform/core/reference/gt-class-methods/translation/download-file).

```typescript title="src/index.ts"
const content = await gt.downloadFile({
  fileId,
  versionId,
  branchId,
  locale: 'es',
});
```

В ответе возвращается содержимое переведённого файла. В этом примере возвращается:

```json title="Output"
{
  "hello": "Hola",
  "world": "Mundo"
}
```

## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/locale-codes

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.