Markdown

How to use General Translation to set up automatic translation for your project's Markdown files

Overview

gtx-cli can be used to automatically translate your project's Markdown (MD and MDX) files.

All syntax and formatting present in the original files will be preserved in the translated files.

We will follow these 4 steps:

Add your environment variables

Install gtx-cli

Configure your project's gt.config.json file


Step 1: Add your environment variables

Add your production API key and project ID to your environment variables. This is necessary to use the gtx-cli tool. You get these from the General Translation dashboard.

.env
GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>

Step 2: Install gtx-cli

Install the gtx-cli tool in your project.

npm i --save-dev gtx-cli

Step 3: Configure your project's gt.config.json file

Create a gt.config.json file in the root of your project, with the following content:

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "mdx": {
      "include": ["docs/[locale]/**/*.mdx"]
    }
  }
}

Change the defaultLocale and locales to match your project's locales.

If your files are MD files, you can use the md key instead of mdx. The string array in the include key should be a glob pattern that matches all of your MDX files.

It should use the [locale] placeholder to match the locale of the file.

See the configuration docs for more information on the gt.config.json file.

Step 4: Add the gtx-cli translate command to your build process

Add the gtx-cli translate command to your build or CI process before the build command to automatically add translations to your project.

package.json
{
  "scripts": {
    "translate": "npx gtx-cli translate",
    "build": "npm run translate && <your build command>"
  }
}

This will generate translations for all of your locales and save them to your project. If you want to commit these files to your repo, you can instead run this command before committing.

You're done! Now your project will automatically update all of your Markdown files any time your project changes.


Notes

  • You can automatically add translations to your project with the gtx-cli translate command.
  • If you want to commit your translation files, you should run the gtx-cli translate command before committing.
  • To configure the output path for your translations, see the configuration docs.

Next steps

On this page