---
tags: tauri-docs-2
---

# i18n

Internationalization (i18n) is an important part of the site. Analytics have shown that the Simplified Chinese translations get a lot of views especially. Although we may not have all content translated nor submitted for community translation, we should build the site with the ability to selectively enable i18n on specific sections of the site.

There are two mainstream options for handling translations:

- Use a git-based approach (Astro does this)
- Use a Crowdin-based approach (how the site is currently run)

This is to discuss the potential benefits and drawbacks of each

## Git-Based

**Pros**

- Easy for devs, instantly see translations inline
- Allows us to potentially do more complex pages without needing to consider external tooling (i.e. Crowdin)
- Can introduce an approval process within GitHub

**Cons**

- Not as friendly for non-technical people who aren't used to git
- Could create a divide on where we store English vs. non-English languages (single source of truth).

A good resource of how Astro does this for their docs site: https://github.com/withastro/docs/blob/main/TRANSLATING.md
Here's how they power a meta-issue for the overall status of translations: https://github.com/withastro/docs/blob/main/scripts/github-translation-status.mjs

## Crowdin-Based

**Pros**

- Nice tools for translators (spell check, etc.)

**Cons**

- Another external tool to maintain
- Can easily break complex pages if a translation results in invalid syntax

## Content Types

We would have longform prose-style documentation and strings within code that would be extracted out to a JSON file.

### Longform Prose

This includes content such as tutorials, how-to guides, and explinations that are more long-form styles of content. This can be highly complex content that could potentially include code and components that should be rendered (such as Astro components).

### JSON File

Strings in `.astro`, `.ts` and `.js` that need to be translated would be wrapped in a `t()` function and then exported into a JSON file. This will allow translations to be performed on the JSON file directly (a copy per locale).

---

# *Below contains previous thoughts that might not all be relevant to the above*

## Historic Issues

To date we've had a hard time with i18n. Our current method is to upload all Markdown, MDX, and derived Docusaurus translations (https://docusaurus.io/docs/i18n/introduction) to Crowdin (https://tauri.crowdin.com).

Crowdin doesn't officially support MDX and the editor isn't friendly with the format (although it does "work"). There have been several times where a trailing `)` or `}` have been missed or a `"` or `'` have been dropped and this breaks the whole build pipeline (for both English as well as the affectived translation).

Docusaurus's i18n solution for JavaScript pages (https://docusaurus.io/docs/i18n/introduction) is actually really elegant and fairly mature. Since we'll be moving away from Docusuaurs and React and into the Astro world we will lose some of that functionality.

Lastly, because Docusaurus treats each locale as a separate site, building a site with multiple languages can cause very long build times and timeout the CI pipelines. Due to this reason we've had to move to a matrix of GitHub runners and build each language individually then combine them together prior to shipping to Netlify. This adds a lot of overhead and also makes us bump our head against a lot of edge cases since this isn't the exact use case Docusaurus was designed for.

## Moving Forward

We should only have only 2 types of files to ship over to Crowdin:

1. Markdown files for the various docs
2. JSON files derived from translation functions within Astro components

### Markdown Files

The primary source of Markdown files will be from upstream documentation (see the high-level architecture diagram in https://github.com/tauri-apps/tauri-docs/issues/1040 to understand how this will be integrated).

These upstream sources will most likely be backed by mdBook. A solution needs to be created to allow opt-in or opt-out of translating whole books and/or specific pages (through frontmatter on specific pages or a config option for the whole book).

The `tauri-docs` repo should be the only repo to sync translations and to integrate with Crowdin as it's the only place where translations will be rendered and will control the "promotion" of docs and guides to the production site.

### JSON Files

For non-MD content this is a bit more difficult. The Astro ecosystem isn't as mature and doesn't have a "stable" i18n solution yet. The closest I've found is https://github.com/yassinedoghri/astro-i18next that is backed by i18next.

The current blocking issue I see with `astro-i18next` is that it doesn't have an out-of-the-box way to extract translations (although a solution is on the roadmap for the 1.0 release https://github.com/yassinedoghri/astro-i18next/issues/19). This issue and it still being in beta make it one of the less stable sections of the architecture.

## CI Pipeline

These are some notes on how the CI pipeline could work for i18n.

1. Clone and copy in upstream documentation (markdown files) to their respective directories.
2. Run a command to extract strings into the JSON files (need a solution for this)
3. Upload Markdown files enabled for translation and the JSON files to Crowdin (https://developer.crowdin.com/cli-tool/)
4. Download translations for enabled languages from Crowdin
5. Copy Markdown files NOT enabled for translation and NOT uploaded to crowdin to the respective language folders
- This step might be somewhere else in the order
- Might need to do it for all file types EXCEPT .astro (handled by `astro-i18n`)
- Need to check if `astro-i18n` will copy over Astro files even if they don't container a `t` function
6. Run `yarn astro-i18n generate` to create the respective Astro files for each language
7. Run `yarn astro build` to export the static site.