Overview

In generaltranslation v8, we’re making significant changes to our API and deprecating some API functions and endpoints.

Older versions of the API will no longer be supported.

generaltranslation versions prior to 7.5 will likely result in errors. gtx-cli versions prior to 2.1.5 will likely result in errors.

---

Motivation

To improve the developer experience, facilitate future development, and make it easier to manage translations, we're introducing branching and deprecating some API endpoints that are no longer in use.

---

Features

The latest API functions support branching, allowing you to create different translations for different branches of your project.

Every file is now associated with a branch. File versioning is now determined by branchId, fileId, and versionId.

Previously, file translations were associated with a single branch. Cached file translations defaulted to using the most recently updated version of the file.

In version 8, updating a file’s translations will now use the latest version of the file on the specified branch. Versioning is tied to a branch’s history, instead of a timestamp.

The new versioning system mirrors Git’s branching model:

• Updating a source file on a branch will create a new version of the file.
• Merging a branch into main will generate a link between the source file on the main branch and the source file on the merged branch.
  • Future translations will incorporate translations from both branches.
• Checking out a branch will create a new version of the file
  • Translations on this branch will reference previous translations from the main branch.

To enable this feature, add the --enable-branching flag to the gtx-cli translate command when using the latest version of gtx-cli.

By default, branching is disabled and all project files are associated with the main branch.

To use this feature, your organisation must be on a paid plan.

Changes

generaltranslation

• Deprecated checkTranslationStatus
• Deprecated downloadFile
• Renamed downloadTranslatedFile to downloadFile
  • Depending on whether a locale is specified, it will either download the source file or the corresponding translation
• Modified parameters of both downloadFile and downloadFileBatch
• Deprecated enqueueEntries
• Modified parameters of enqueueFiles (added branchIds)
• Deprecated fetchTranslations
• Deprecated shouldSetupProject
• Modified parameters of submitUserEditDiffs (added branchIds, made id fields required)
• Modified parameters of uploadSourceFiles (added branchIds)
• Modified parameters of uploadTranslations (added branchIds)
• Modified parameters of querySourceFile (added branchIds)
• Added checkJobStatus
• Added queryFileData
• Deprecated checkSetupStatus (use checkJobStatus instead)
• Deprecated checkFileTranslations (use queryFileData instead)

gtx-cli

• Added --enable-branching flag to the translate command
• Added --branch flag to the translate command
  • (Optional) Override the branch to use for the translation
• Added --disable-branch-detection flag to the translate command
  • (Optional) When disabled, the CLI will not automatically attempt to detect branches to use.
  • Use this flag if git is not installed or if the project is not a git repository.
• Improved translation progress tracking and logging
• Improved translation error handling
• Optimised API performance to avoid unnecessary API file uploads

gt-sanity

• Updated to use the latest version of generaltranslation
• Translations now default to using the main branch.
  • Support for document draft preview branching will be added in a future release.