Translating Documentation Guide

Last Updated   March 31, 2025

Guide

Updating Translations for Existing Pages

When a page already exists in the translation you are working on, you can update the translation by following these steps:

1. Go to the page you want to translate.

2. Using the language dropdown at the top of the page, select the language you want to translate the document into.

3. Click the “Edit page” button at the bottom of the page.

4. Translate the content into the selected language.

5. After making your changes click the “Commit changes…” button at the top of the page.

6. In the modal that appears, add a title and description to describe your changes, then click the “Propose changes” button.

7. In Discord ping @Revelry to review your changes.

Adding a Page to Existing Translation

When browsing the documentation site, you may find a page that is not translated into the language you are viewing. If this is the case you might see a banner at the top of the page similar to the one below:

If you see this banner you will need to create a copy of the page in the translation directory for the language you are viewing, and then following the steps outlined in Updating Translations for Existing Pages.

Once a language has been added to the astro config file you can create a new file in the src/content/docs/ directory inside a folder named with the language code. This new file should have the same name as the original file you are translating.

For example, if you are translating the src/content/docs/getting-started.mdx file into Spanish you would create a new file at src/content/docs/es/getting-started.mdx with the Spanish translation of the content.

More detailed instructions for how to do this will be added in the future.

Adding new languages to the language dropdown

If you want to add a new language that is not currently available in the language dropdown, you can do so by following these steps:

For more information, see Starlight - Configure i18n.

Important Notes

• The root language should not be changed from English.
• When adding a new language, you should also update the existing translation blocks in the astro config file to include the new language.

How to reference UI elements in translations

Since the Hardcover app is currently only available in English, you should write the documentation pages with the English labels but also include what the translation should be.

For example, if you are translating a page that references a button with the label “Save”, you should write the page with the button labeled as “Save” and include the translation in the page content like so:

Click the <kbd>Save</kbd> button to save your changes.

Would become:

Haga clic en el botón <kbd>Save</kbd> "Guardar" para guardar los cambios.

Using the new translations

See Using Translations in Doc Pages for more information on how to use the new translations in your documentation pages.