How to Localize Your Astro Website for Global Audiences (using Crowdin)

Integrating a Translation Management System (TMS) in an Astro-based website ensures global access to your application.

Localization is a core aspect of this process. It ensures you can:

• Adapt an application to meet the cultural, language, and other requirements of a country or region.

Let’s walk through how to set up language sub-paths and connect to Crowdin—a popular localization tool—in an Astro context.

Crowdin Overview and Localization

Crowdin is a cloud platform that facilitates the localization process for organizations by streamlining the translation of their content into multiple languages.

It's used in internationalization(i18n) efforts to make managing translations and working with translators easier.

To translate an Astro site, we recommend the below translation workflow:

• Upload the files you need to be translated

• Translate files using Crowdin

• Download your translated files from Crowdin

Crowdin offers a command-line interface (CLI) that enables you to upload source files and download translated files, allowing you to automate the translation process.

You can learn more about translation workflows in the official Crowdin documentation.

Overall, Crowdin offers tools such as:

• Translation memory

• Terminology management

• Project management: Helps teams effectively translate and maintain their content across multiple languages

Getting Started with Crowdin

In this tutorial, we will use Crowdin to translate an English Astro website into French.

To follow along, you can view the complete code solution on this GitHub repository.

But first, let's see how we can initiate our project in Crowdin. Typically, you would follow these steps:

1. Sign up for a Crowdin account and create a project.

   

2. Add the project name, source language, visibility, and target languages. In our case, English will be the source language and French will be the target language.

   

3. Upload the content you want to translate, such as documents, strings, or multimedia files.

   

4. Define your target languages and invite translators to join your project.

5. Translators can access and translate the content directly in the Crowdin platform, using built-in translation tools such as translation memory and glossary management.

6. Reviewers can review the translated content and provide feedback or approve it.

Once Crowdin approves the translations, you can download the translated files and use them in your localized product or website.

You’ll need to update and maintain the translated content in Crowdin as you update your source content.

Astro Site Preparation

Astro is a web development tool for building fast websites focusing on content.

Let’s initialize a new Astro site:

# npm
npm create astro@latest

# pnpm
pnpm create astro@latest

# yarn
yarn create astro

Next, add the configuration for Spanish or French language.

To do so, you can add your translated files from Crowdin in the matching language-specific JSON file within Astro, typically found in the src/lang directory of your Astro project. For instance, for French translations, you can insert the translated content in the fr.json file, while for Spanish translations, you can include the content in the es.json file.

As we’re translating our homepage, here are the translations for Spanish and French:

# src/lang/es.json - Spanish

{
    "Welcome to the official Astro Translated Site": "Bienvenidos al sitio web oficial de Astro traducido",
    "Have fun! See more on the GitHub repository": "¡Diviértete! Obtén más información en el repositorio de GitHub"
}

# src/lang/fr.json - French

{
    "Welcome to the official Astro Translated Site": "Bienvenue sur le site officiel d'Astro traduit",
    "Have fun! See more on the GitHub repository": "Amusez-vous! En savoir plus sur le référentiel GitHub"
}

Crowdin CLI Configuration

In Astro, you can incorporate Crowdin CLI in your project to:

• Handle and translate language files.

• Automate how to get the most recent translations from Crowdin

• Create translation files

• Upload updated translations to Crowdin

Install Crowdin CLI:

npm install -g @crowdin/cli

Test that you have installed Crowdin successfully:

crowdin --version

To configure Crowdin CLI in your project, run the following prompt:

crowdin init

You’ll be prompted to enter your Crowdin project identifier and API key.

To set up the Crowdin CLI for your Astro project, generate a crowdin.yaml file in the main directory of your project. This file will hold the configuration settings that Crowdin CLI will use.

# <project-name>/.crowdin.yaml

"project_id": "projectId"

#Tells Crowdin to use the environment variable “personal-access-token” as your API token.
# You may need to set this variable on your hosting service with your actual API token generated by Crowdin
"api_token": "personal-access-token"

#Tells Crowdin to use the current directory as the base path for your source and translation files
"base_path": "."
"preserve_hierarchy": true
"base_url": "https://api.crowdin.com" # https://{organization-name}.crowdin.com for Crowdin Enterprise

"files": [
  {
    "source": "/src/lang/en.json", # Source line tells Crowdin CLI3 to upload the en.json in the src/lang directory.

#source files filter
# This line allows Crowdin to download the translated files to the same directory
#structure but with a two-letter code prefix.
    "translation": "/src/lang/%two_letters_code%.json" 
  },
]

VCS (Git) Integration

Crowdin provides VCS (version control systems) integrations for different platforms, including GitHub, GitLab, Bitbucket, and other popular VCS platforms such as Azure Repos, Bitrise, and CircleCI.

• GitHub: Integration supports various GitHub workflows, such as pull request and push notifications, branch updates, and automatic commits.

• GitLab: The integration allows you to synchronize your source and translation files with your GitLab repository, manage your project languages, and track translation progress.

• Bitbucket: Integrations allow you to automate updating your source and translation files.

However, we experienced a few caveats when integrating Crowdin with Git:

• Conflict resolution: When using Git-based localization workflows, conflicts can arise if multiple translators work on the same file. While Crowdin provides conflict resolution tools to handle such conflicts, it is important to plan how to resolve such potential conflicts.

• Maintenance: As your localization project grows larger, maintaining it can become hectic. This involves tasks like keeping localization files up-to-date, ensuring translations align with the source material, and periodically reviewing the localization process.

Setting Up Language Sub-Paths in Astro

Organizing translations for your website or application to language sub-paths in Astro is easy.

It simplifies the management process and guarantees a consistent user experience across your application.

Setting up these sub-paths involves including the "lang" parameter in your Astro routes, making the process straightforward. The sub-paths create distinct paths for each section of your site, each with its translations.

In the example below, we show a simple use case of implementing language sub-paths in Astro using a JSON file for translations:

routes:
  - path: /{lang}/home
    action: pages/home
  - path: /{lang}/about
    action: pages/about
  - path: /{lang}/contact
    action: pages/contact

We add the lang parameter to each route in this example that allows you to specify a different language for each section of your website. For instance, when a user visits /en/home, they will see the English version of your home page. If they go to /fr/home, they'll see the French version.

To use language sub-paths in Astro, you need to add the lang parameter in your Astro routes, as shown in the example above. You'll also need to perform separate translations for each section of your site, using the same key for each translation in each language.

To access the translations in your Astro routes, use the t function offered by Astro. Below is an illustration of how to retrieve the title and description for the English version of your home page:

{{ t("home.title") }}
{{ t("home.description") }}

Connecting Crowdin in an Astro Context

Connecting Crowdin—a localization management system—to Astro is easy using the APIs Crowdin provides. To integrate Crowdin with Astro, follow these steps:

• Create a project in Crowdin and set up your translation workflows and memory.

• Connect your repository to Crowdin to sync your source files and translations.

• You can utilize Crowdin’s OTA JavaScript client to access translations in your Astro web application. It’s a lightweight library that provides translated content to users much faster and easier.

Here's an example of using Crowdin to manage translations on an Astro website:

• In Crowdin, create a new project and upload the source files you need to translate.

• Set up the translation workflows, translation memory, and terminology management.

• Connect your repository to Crowdin to sync your source files and translations.

• In your Astro application, use Crowdin’s OTA to retrieve the translations for a specific language.

To switch between languages, use the lang parameter in your Astro routes. For example, when a user visits /en/home, the API will retrieve the English translations. If the user visits /fr/home, the API will retrieve the French translations.

i18n Implementation in Astro

Internationalization, or i18n, in Astro, refers to changing a web application to support multiple languages, date and time styles, and number styles. Below are common i18n scenarios you can execute in Astro, accompanied by illustrations and descriptions using code examples.

Multiple Language Management

Astro gives developers two options for handling language implementations:

• utilizing a translation management system such as Crowdin or,

• through storing the translations in a JSON file.

To access the translations, you can use the t function provided by Astro. We use C# to manage English and French translations, as shown in the example below.

// English translations
{
  "home": {
    "title": "Home",
    "description": "Welcome to the home page"
  }
}

// French translations
{
  "home": {
    "title": "Accueil",
    "description": "Bienvenue sur la page d'accueil"
  }
}

// Retrieve the translations in your Astro route
route.get("/:lang/home", (req, res) => {
  const title = t(req.params.lang, "home.title");
  const description = t(req.params.lang, "home.description");

  res.send({ title, description });
});

Considerations for Crowdin as a Translation Management System using Astro

There are aspects to consider when working with Crowdin as a TMS with the Astro web framework. These factors may need paying attention to before you can get started with your application:

• Integration: Ensure that Crowdin integrates seamlessly with the Astro framework.

• Translation process: Make sure that you have a simple process for handling translation requests, revisions, and approvals.

• Terminology management: Use Crowdin's terminology management feature to ensure you use consistent terminology throughout the translation process.

• Translation memory: Use Crowdin's translation memory feature to store and reuse translations for frequently used phrases and sentences.

• Project management: Use Crowdin's project management tools to keep track of the translation process, deadlines, and progress.

• User management: Consider setting up user roles and permissions within Crowdin. This allows you to manage access to the translation project and ensure that the right people have access to the right information.

• Performance: Test the integration between Crowdin and Astro to ensure its success in production.

• Error handling: Handle errors gracefully and log them meaningfully so you can debug and resolve issues when they arise.

Wrapping Up

By utilizing Astro and Crowdin, we can streamline the localization process, resulting in a web application accessible to a diverse global audience.

Crowdin offers the advantage of efficient translation management, resulting in a consistent user experience, regardless of the language used.

Check out a minimalistic Astro web application on GitHub.