Overview

In generaltranslation v8, we're making significant changes to our API, and are 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 were no longer used.

---

Features

The newest API functions support branching, which allows 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 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 on 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 org 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 or corresponding translation
• Modified params of both downloadFile and downloadFileBatch
• Deprecated enqueueEntries
• Modified params of enqueueFiles (added branchIds)
• Deprecated fetchTranslations
• Deprecated shouldSetupProject
• Modified params of submitUserEditDiffs (added branchIds, made id fields required)
• Modified params of uploadSourceFiles (added branchIds)
• Modified params of uploadTranslations (added branchIds)
• Modified params 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 translate command
• Added --branch flag to translate command
  • (Optional) Override the branch to use for the translation
• Added --disable-branch-detection flag to 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
• Optimized API performance to avoid unnecessary API file uploads

gt-sanity

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