🌐 i18n and Translation

Thanks for your interest in helping us translate docs.astro.build! This can be a great way to get involved with open-source development without having to code.

Currently, we are aiming to translate the Astro documentation into the following languages:

Arabic
Brazilian Portuguese
Chinese (Simplified/Traditional)
English
French
German
Hindi
Italian
Japanese
Korean
Polish
Russian
Spanish

We can currently support the above languages thanks to active community translators willing to volunteer their time to contribute with translations and reviews! Unfortunately, we cannot support all languages at this time, and must prioritize based on available community members and their needs. Adding a language means allocating additional resources to attracting new contributors, and maintaining changes to our code base in multiple languages. We will not add any new languages that we haven’t approved beforehand, and we cannot approve a new language without a group of people prepared to undertake significant work to translate our entire site.

How can I contribute?

We receive several translation PRs to our repository daily, meaning one of the most helpful and impactful ways to contribute is through reviews so that all of these wonderful translations can be properly checked before being published. Keep reading to find out how to contribute on GitHub!

If you’re a beginner when it comes to reviewing GitHub PRs and translations, we got you covered in our Reviewer Process section.

Join our Community on Discord

Before making any contribution, we highly recommend joining our Discord chat first. There, access the “Channels & Roles” menu and select your language, which should make a docs-i18n channel pop up. Send us a hello message there and the language you’re interested in contributing, so that we can add you to the language’s crew own thread for discussion and planning.

Joining us on Discord means we can answer any of your questions and allow you to chat with your teammates to avoid duplicate work. All of our internationalization decisions and discussions happen there, meaning it is the best place to find out which patterns and recommendations your language’s translation crew follows and get yourself involved in the decision-making process.

Getting started

Visit our translation tracking system, where the current status of all pages can be seen, including what needs to be updated in them and the open PRs waiting for reviews. It works by fetching our local git history, which compares the date of the changes made in the different translations of a page and updates its status accordingly.

You can also visit GitHub directly and go through your language’s open Pull Requests with the i18n label needing review and see if there are any mistranslations, typos, or sentences hard to read. This will also be a good first lesson on how Astro Docs’ i18n works.

Structure of Astro Docs

The docs repository contains three different kinds of translatable content: docs pages, UI strings, and navigation labels. The following file tree shows where to find these in the repository.

…
Directorysrc/
- …
- Directorycontent/
  - Directorydocs/ MDX page content, one directory per language
    Directoryar/
    …
    Directoryde/
    …
    Directoryen/
    …
    …
  - Directoryi18n/ UI string translations, one file per language
    ar.yml
    de.yml
    en.yml
    …
  - Directorynav/ Sidebar navigation label translations, one file per language
    ar.ts
    de.ts
    en.ts
    …
- …
astro.config.ts
package.json
…

Docs pages

Each documentation page lives in the src/content/docs/ directory of the docs repo. There you’ll find a directory for each currently supported language. Each page is an MDX file to support rich text formatting and Astro components.

For example, the English language “Getting Started” page is at src/content/docs/en/getting-started.mdx and the same page in French is at src/content/docs/fr/getting-started.mdx.

Reusable UI strings

We also have translations for UI text strings. These are short bits of text used to label or structure components of the documentation UI. For example, the text “Sponsored by” before our sponsor logos on the English pages is translated so we can show “Sponsorisé par” on the French pages instead.

UI strings are stored in the src/content/i18n/ folder, with a dedicated YAML file for each language. Unlike pages, these translations look more like a dictionary, mapping standard keys to translated strings. Comments can be included on a line starting with a #.

The following example shows an abbreviated version of the English UI strings:

a11y.sectionLink: Section titled
# Site settings
site.title: Astro Documentation
# Left Sidebar
leftSidebar.sponsoredBy: Sponsored by
# ...

Keys are not translated, so the example above is translated into French as:

a11y.sectionLink: Titre de la section
# Site settings
site.title: Documentation Astro
# Left Sidebar
leftSidebar.sponsoredBy: Sponsorisé par
# ...

See the English or French files in the docs repo as examples of a what a full file looks like.

Similar to reusable UI strings, labels for the groups displayed in the docs sidebar are translated in their own file.

Navigation labels are stored in the src/content/nav/ folder, with a TypeScript file for each language. The en.ts file in this folder contains the English text displayed in the sidebar for each key.

The non-English files must contain a default export using the navDictionary() helper method. Just like for UI strings, keys are not translated, only the values in the object passed to navDictionary().

The following example shows an abbreviated version of the Simplified Chinese translation of the sidebar navigation labels:

import { navDictionary } from '../../util/navDictionary';

export default navDictionary({
  start: '开始',
  'start.welcome': '欢迎，世界！',
  'start.newProject': '开始新项目',
  // ...
});

See the English file in the docs repo for all the label keys currently in use and the Simplified Chinese file as an example of what a fully translated file looks like.

Translation Process

To start working on translating a part of docs.astro.build, the first step is to figure out where the content lives in this repo:

Is the text in the navigation menu (left sidebar on desktop, hamburger menu on mobile)?

➤ Go to src/content/nav/{language}.ts
Is the text reused on several pages (e.g. search modal, right sidebar, article navigation, tutorial, etc.)

➤ Go to src/content/i18n/{language}.yml
Is the text specific to one page (page title, main content, etc.)?

➤ Go to src/content/docs/{language}/{page-slug}.mdx

After you’ve found what you want to translate, check the Translation Tracker and the open PRs to see if anyone’s already done it. If not, tell your fellow translation crewmates you’re on it to avoid someone else from working on the same page!

What to translate

You’re free to choose the pages you feel the most comfortable or excited about, but if you’re asking yourself “What should I translate next?”, this section is here to help you.

We’ve separated pages into categories, mostly according to Astro Docs’ sidebar organization. Each category is described with an approximate view count, maintenance cost, and page size stats, as well as a description explaining the rationale and other tips.

Start Here

View Count: High
Maintenance: Low
Size: Medium

The “Start Here” pages are some of the most visited pages in the whole documentation thanks to being the entry point for new Astro users. They’re mostly small, averaging at 150 lines, contain little terminology, and rarely change.

This means these pages are also a good entry point for new translators, especially for recently-added languages who need to build up their own glossary and attract new contributors to the language.

An exception is the “Upgrade to vX” guides, which are bigger, contain more terminology than most pages, and have fewer visitors after the first months after a new major release. The content will not change, but these pages become less useful over time.

Core Concepts

View Count: High
Maintenance: Low
Size: Small

The “Core Concepts” pages explain the reasons to use Astro, its design principles and its architecture. These are among our most viewed pages and are smaller than average, having less than 100 lines each and also rarely changing. On the other hand, these pages introduce considerably more terminology than the “Start Here” pages, making them more complex to translate.

Tutorials

View Count: High
Maintenance: Medium
Size: Medium

The “Tutorials” pages include learning-oriented guides on Astro and its features. These pages are especially seen by beginner Astro developers, complex terminology is kept to a minimum, and what is there is well-explained for beginners in small to medium-sized pages.

Even though these pages may be small, they are cummulative, demanding more of translators and reviewers to keep a consistent language across all pages. Translators may need to look at past or future pages to ensure that they are using a consistent vocuabulary and phrasing. Tutorials are also constantly updated based on user feedback, meaning changes are more frequent but generally lesson-specific.

Reminder: You are welcome to update existing tutorial translations, but you must seek guidance before starting to translate a tutorial that does not yet exist.

Basics

View Count: High
Maintenance: Low
Size: Medium

The “Basics” pages document some of the main features of Astro. On average, these are bigger and more complex than the sections above. However they do not often change, and are highly viewed, making them very useful to have and easy to keep up to date.

Built-ins

View Count: High
Maintenance: Medium
Size: Big

The “Built-ins” pages include Astro features you can add to your project by opting into them, these are highly viewed while at the same time introducing several new terms in bigger pages that are frequently improved during minors, increasing its maintenance cost.

Add-ons

View Count: High
Maintenance: Low
Size: Medium

The “Add-ons” pages explain Astro features and support that you can add by installing integrations, also serving as a “portal” for specific integration pages. Overall, these have an average size and low maintenance cost, despite introducing some more complex terminology to translate.

Integrations

View Count: Medium
Maintenance: Medium
Size: Medium

The “Integrations” pages are sub-pages available at the root “Add integrations” page. These considerably vary in size, maintenance cost, and complexity. The “UI Frameworks” integrations are smaller and easier to maintain, while the others average bigger sizes and are more bound to go through changes.

The most viewed pages by category, by a considerable margin, the @astrojs/react, @astrojs/node, and @astrojs/tailwind pages.

Each integration page contains several specific terms about the integrated technology, increasing the translation complexity especially for those not familiar with it.

Recipes

View Count: Medium
Maintenance: Super Low
Size: Extra Small

The “Recipes” pages are portals to task-oriented, how-to guides from migrating to Astro from another technology to deploying to a specific platform.

Since the content most users will look for is in the sub-pages, the root Recipe pages are one of the smallest and with less complexity of the whole documentation, being easy wins for any translators wanting to get some pages done quickly.

Migrate to Astro

View Count: Low
Maintenance: Medium
Size: Big

The “Migrate to Astro” pages explain how to move from another technology to Astro. Most of these are “stubs”: smaller guides that link to related community resources, while others contain very detailed code samples and migration tips, being one of the biggest pages in our docs.

If you’re looking for quick wins, the stub pages should be straightforward to translate at a pleasant pace, while the complete ones are bigger and have more complexity, recommended for more experienced translators and users of said technology.

CMS Guides

View Count: Low
Maintenance: Low
Size: Medium

The “CMS Guides” pages explain how to use Astro alongside a specific content management system. Most are “stubs” that serve to link to outside resources generally from the CMS’ official documentation, while others contain medium-sized guides.

On average, CMS pages contain less and simpler terminology than other 3rd-party content guides. Any of the stub pages should be quick wins while the most complete ones have an average maintenance cost and size.

Backend Services

View Count: Low
Maintenance: Low
Size: Medium

The “Backend Services” pages explain how to use backend services alongside Astro, mostly database or auth-related.

Most of them are small “stub” pages, with little to no maintenance cost, with higher complexity and size for our most viewed guides: Firebase and Supabase.

Deploy Guides

View Count: Low
Maintenance: Low
Size: Small

The “Deploy Guides” pages explain how to deploy Astro to specific hosting platforms, be it statically or with SSR.

Deploying Astro to most hosting platforms is a straightforward task since many support zero-configuration deploys for Astro projects and contain official documentation on using Astro.

As a whole, deploy guides are quick wins, not containing a lot of terminology and having small page sizes.

More Recipes

View Count: Low
Maintenance: Low
Size: Medium

The “More Recipes” guides include task-oriented guides based on several of Astro features and use cases, most pages are small, or rather, code-heavy, containing less complex terminology, making most of them quick wins for any translators, especially those not used to all of Astro’s terminology yet thanks to the recipe’s self-contained approach.

Guides

View Count: Medium
Maintenance: Medium
Size: Medium

The pages under “Guides” include information about some of Astro’s most commonly used features, and are highly visited. These are average-sized, with a fairly complex sample of terminology for each feature. They regularly receive incremental changes at minor release time, especially for experimental features.

Configuration

View Count: Medium
Maintenance: Low
Size: Small

The “Configuration” guides teach you how to configure Astro and other features in your project. Most are small pages that rarely rarely change. Most of the terminology used on these pages is common across several projects, not just Astro, making it less complex to translate and with vocabulary that you can find on other translated web sites.

Reference

View Count: High
Maintenance: High
Size: Big

The “Reference” pages include API documentation for several parts of the Astro codebase, including the biggest pages in the whole documentation. Each page will contain plenty of terminology, and will change during minor and major releases. We recommend for more experienced translators to tackle these pages as they may require very specific Astro knowledge.

Error Pages

View Count: Super Low
Maintenance: Super Low
Size: Extra Small

The error pages are definitely the smallest, least complex, and rarely changed pages in the entire documentation. With currently more than 50+ different error pages, tackling them is a quick and impactful win in increasing a language’s translation coverage. This is also one of the most helpful translations you can choose for your fellow language speakers so that they can better understand issues with their projects.

Review Process

The review process is a very important step in our internationalization work, enabling us maintainers to quickly and reliably merge new translations knowing the content has been both translated and reviewed for accuracy. Whether your work is being reviewed or you are reviewing someone else’s translations, we have a few tips for you!

Reviewing someone else’s PR

It can be confusing to know what exactly should be reviewed! Mostly, what we are looking for is another pair of eyes to catch any obvious mistakes. If that is all you do, you have been a HUGE help!

Just ask yourself: does anything seem “out of place” or “unusual” when I read it? Are there typos or any word choices that I would not expect to read? This might not mean the translation is “wrong” but is worth mentioning if a word choice is distracting when reading documentation. You’re also free to suggest small deviations from the original text if that means making a sentence that reads better in your language or culture.

If you want to take your reviews to the next level, here are some more questions you can ask yourself while reviewing translations:

Is the translation correctly written following the translated language’s norms and practices?
Did the translation deviate from the original in a way that important information is being missed somehow?
Is the translation consistent with the language’s style guide and glossary?
Are there any UI labels or content missing translation?
Are the custom components, asides, and code samples being properly displayed in the Deploy Preview?
Do the code samples’ titles, syntax highlighting (like js or astro), and highlighted lines match the English version?
Are there any links that could be localized? (e.g. Wikipedia and MDN links)

Our maintainer’s team does not know all the languages available for translation, and this is the valuable assistance that you are providing us! When you think a PR is good to be merged after your suggestions were addressed (if any), approve it through GitHub’s “Review Changes” button or leave a “LGTM!” in the comments to let us know. (“LGTM” is an abbreviation of “Looks Good to Me”, often used to approve pull requests.)

If you are not used to approving PRs or suggesting changes on GitHub, read about how to review and suggest changes on GitHub Docs.

Getting a review on your own PR

After publishing your own i18n PR, make sure to share it in your language’s i18n-crew thread, where other contributors will be able to notice it quickly and review it sooner. Do not spam repeatedly with requests to review. All contributors are voluntarily taking their time, and if a few weeks have passed without any reviews, Astro maintainers will gently nudge contributors and proceed with the review ourselves if necessary.

When you receive a review, do not worry if you see a lot of suggestions made correcting your work. It doesn’t mean you did a bad job! There are lots of things to account for when translating, including choices made by previous translators which we must match for consistency. Each language crew makes its own decisions based on which words do or do not get translated, as well as the level of formality and whether certain phrases are acceptable, for example. And, everyone makes typos and mistakes, or and it usually takes other people to notice them! There is usually a lot of discussion in a translation PR because of our active, dedicated community that wants to see the best docs possible!

If your PR is full of suggestions and you want to accept and commit them all quickly, see how you can batch suggestions and merge them as one commit on GitHub Docs.

Quality Standards & Adaptation

We are only able to maintain multiple translations of the docs thanks to our amazing team of volunteers, who are prepared to spot typos and fix the occasional grammatical errors. Translations requiring significant editing cannot be accepted and for that reason, we may close PRs that don’t meet our criteria.

Translations should be faithful representations of the English text, at a native speaker’s grammar level, without changes to the meaning and structure of a page. It is valid to make small deviations to a sentence order or structure if that means a better understanding of the text in the translation.

We expect translators to be Astro users so that they are familiar with Astro terms and concepts; however, reviewers who are less familiar with Astro are welcome to review for typos and grammar errors and other language edits!

Pull Request Guidelines

To make it easy to find and organize our i18n PRs for both maintainers and reviewers, please follow the following guidelines:

To easily identify a PR’s language, we recommend titles in the form i18n(language): add/update page translation, for example:
```
i18n(pt-BR): Update `markdown-content.mdx` translation
```
```
i18n(ar): Add new `markdown-content.mdx` translation
```
PRs should be small. They can include multiple pages/files if each page has only a small number of lines changed, but avoid updating more than 2 or 3 pages at a time in the same PR. By doing so, we allow reviewers to go through individual PRs and approve them more quickly. Many small PRs to review are less overwhelming and each one can be merged on its own as soon as it is approved. This helps prevent large PRs from taking a long time to review and revise, and can avoid content becoming out of date.
Add to the initial PR comment any questions you have, anything that you found difficult, or issues you had along the way. This helps maintainers and reviewers to know if they need to look at anything more closely. You can even “review your own PR” and add thoughts, comments, or questions to your own PR, making it easy for others to spot potential issues that require discussion!
If your PR only makes a minor fix but does not update the entire page to be current with the English version (e.g. a typo or broken link on a page that still does require updating), you will need to add [i18nIgnore] to the PR title so our Translation Tracker won’t mistake it with a complete update. This will prevent our tracking system from assuming the page is fully updated to match the English version, but still allows you to fix an urgent mistake. For example:
```
[i18nIgnore] i18n(fr): update `astro-components.mdx` code sample
```

Language Guides

Translators are free to create and maintain a glossary, style guide, and other tips for their language’s translation crew. This is a great way to keep translations consistent across contributors and to centralize team decisions. You can find it (or create it) inside the language’s i18n folder as a README.md file.

Feel free to take a look at the Deutsch Guide for an example.

Tutorials

The pages under the tutorial/ directory belong to the “Create a Blog” tutorial, which is a linear sequence of lessons to introduce users to Astro concepts. It would be distracting to follow a tutorial with only some of its pages translated, therefore we cannot merge a tutorial translation PR before it’s been fully translated.

Translating the entire tutorial is a huge job for one translator, and as we care about making our workflow sustainable, we’ve made a different workflow specifically for the tutorial pages to avoid burdening any contributor working on them. Please only start translating the tutorial if you intend to finish it! :D

As with any other PR, it is recommended to be small, something between 1 to 3 lessons (each lesson is its own .mdx file) or a full unit if small (equivalent to a chapter of the tutorial).

If there isn’t an existing language/tutorial branch to target, publish your PR to the main branch and we will take care of creating it and updating your PR to merge there instead. After the first PR has been merged, one maintainer will create a WIP (Work in Progress) PR to merge this branch into main.

This allows for the smaller pieces of the tutorial to be translated by different contributors and merged without showing up on the main site before its fully completed.

Reference

We welcome new or inexperienced contributors and also Astro users not familiar with our Docs repo and configuration! Below is a helpful guide on how certain elements should be translated or treated.

Frontmatter

Our pages are generated from MDX files which have frontmatter properties. These are variables that hold information about the page (values) that we later use to specify the page’s title, description, and other special data.

Here’s an example file showing the properties of layout, title, description, and i18nReady along with their corresponding values for this page.

---
layout: ~/layouts/MainLayout.astro
title: Data Fetching
description: Learn how to fetch remote data with Astro using the fetch API.
i18nReady: true
---

// Rest of the file's content is here...

TL/DR: Translate only some values, never translate properties!

The frontmatter properties themselves, like title and description, should not be translated, as doing so would cause a runtime error and break our CI.

The only frontmatter values that should be translated are those corresponding to the title and description properties, for example: “Data Fetching” and “Learn how to fetch remote data with Astro using the fetch API.”

Other frontmatter properties that aren’t mentioned here should be ignored and not translated, as we use them for handling our “Edit this page” link or for specifying to which category an integration belongs, etc.

Here is the above example correctly translated:

---
layout: ~/layouts/MainLayout.astro
title: Fetching de datos
description: Aprenda como obtener datos remotos con Astro utilizando la API de fetch.
i18nReady: true
---

// Rest of the file's content is here...

Code Samples

We have lots of code samples throughout our docs, and although we recommend translating comments, as they give a contextual clue of what’s happening in the code, each language is free to decide whether or not they want to translate titles, variables, string values, function names, etc.

Be aware that if code samples are being translated, you may need to update some of the code sample’s highlighted lines. Read the Code Samples section in our Writing Guide to learn more about their syntax. Astro uses Expressive Code for customizable code snippets.

Asides

Most of our pages include stylish tip/note/caution blocks called “asides”. We use a custom syntax to author them which includes the type of aside (all lowercase) and optionally a custom title in square brackets. Here is an example of a “tip” found in the docs:

:::tip[Online previews]
Prefer to try Astro in your browser? Visit [astro.new](https://astro.new/) to browse our starter templates and spin up a new Astro project without ever leaving your browser.
:::

Do translate: the custom inline labels inside [square brackets], and the text inside the aside block.

Do not translate: the aside’s type (e.g. :::tip). These type names are instead translated once in each language’s i18n/nav.ts file and are automatically replaced in your translated page as necessary.

Here is the above example correctly translated:

:::tip[オンラインプレビュー]
ブラウザで Astro を試してみませんか？[astro.new](https://astro.new/)では、スターターテンプレートを利用し、ブラウザから離れることなく、新しい Astro プロジェクトを立ち上げられます。
:::

Components

Astro allows us to import and include custom components in our pages using MDX. Take this fragment of the islands.mdx page, which renders a diagram, as an example:

<IslandsDiagram>
  <Fragment slot="headerApp">Header (interactive island)</Fragment>
  <Fragment slot="sidebarApp">Sidebar (static HTML)</Fragment>
  <Fragment slot="main">Static content like text, images, etc.</Fragment>
  <Fragment slot="carouselApp">Image carousel (interactive island)</Fragment>
  <Fragment slot="footer">Footer (static HTML)</Fragment>
  <Fragment slot="source">
    Source: [Islands Architecture: Jason Miller](https://jasonformat.com/islands-architecture/)
  </Fragment>
</IslandsDiagram>

Do translate: slotted content (content between the opening and closing tags).

Do not translate: import statements, component names, and slot names (like slot="headerApp").

Here is the above example correctly translated:

<IslandsDiagram>
  <Fragment slot="headerApp">Cabeçalho (ilha interativa)</Fragment>
  <Fragment slot="sidebarApp">Barra lateral (HTML estático)</Fragment>
  <Fragment slot="main">Conteúdo estático como texto, imagens, etc.</Fragment>
  <Fragment slot="carouselApp">Carrossel de imagens (ilha interativa)</Fragment>
  <Fragment slot="footer">Rodapé (HTML estático)</Fragment>
  <Fragment slot="source">
    Fonte: [Arquitetura em Ilhas: Jason Miller](https://jasonformat.com/islands-architecture/)
  </Fragment>
</IslandsDiagram>

Note that some of our components’ labels are instead translated inside the language’s respective i18n/ files.

Generated pages and warnings

Some of our English page content is generated from outside sources, and must not be edited directly in this repository. We show dev-only warnings to prevent contributors from changing that English content here, and instead, guide them toward the proper source location of the English content.

However, these pages are translated directly here and these warnings are not meant for translations.

For these generated pages (like configuration-reference.mdx), we recommend ignoring and removing the note and component (including its import) from the file, thus avoiding confusion for other translators thinking that this warning applies to translations as well.

We also might include comments warning about specifics that should be done in translations. Please always read the top of the file when you begin to work on a page, follow what’s described and if no longer needed, you can remove the comment in the translated file.

Adding a new language

Prerequisites

To get started adding a language, you’ll need:

Its BCP 47 tag

Examples: en / pt-BR / ar

This will be used for the HTML lang attribute and as the base for URLs for this language, e.g. /{tag}/getting-started. These tags can encode script-type and regions as well as language, but most often we will only need the language part unless we want to distinguish regional variants (as in the pt-BR example above).

Resources:
- Choosing a Language Tag (in-depth guide)
- Subtag lookup web app
- IANA subtag registry
Its name as written in the language

Examples: English / Português do Brasil / العربية

This will be used to label this language in the site’s language switcher and potentially elsewhere. The best way to get this is probably to ask the person leading translation work for this language.

🌐 i18n and Translation

How can I contribute?

Join our Community on Discord

Getting started

Structure of Astro Docs

Docs pages

Reusable UI strings

Sidebar navigation labels

Translation Process

What to translate

Start Here

Core Concepts

Tutorials

Basics

Built-ins

Add-ons

Integrations

Recipes

Migrate to Astro

CMS Guides

Backend Services

Deploy Guides

More Recipes

Guides

Configuration

Reference

Error Pages

Review Process

Reviewing someone else’s PR

Getting a review on your own PR

Quality Standards & Adaptation

Pull Request Guidelines

Language Guides

Tutorials

Reference

Frontmatter

Code Samples

Asides

Components

Generated pages and warnings

Adding a new language

Prerequisites

Resources: