Astro Websites Localization and Internalization
Tags: engineeringteams, framework
Published: 2023-07-12 09:21:21

In this article, you will learn the basics of Astro localization, so you can make your website multilingual to reach new markets. We’ll discuss i18n and localization best practices that will ensure that you can adapt an application to meet the cultural, language, and other requirements of a country or region you’re targeting.

Integrating your localization software with an Astro-based website is an important step to automating the localization process.

Let’s start with a walk-through on how to set up language sub-paths and connect [Crowdin](https://crowdin.com/) to your Astro project.
## Getting Started with Astro localization
In this tutorial, we will use Crowdin to translate an English Astro website into French and Spanish.

Let’s see how we can initiate our project in Crowdin. Typically, you would follow these steps:

1. Sign up for a Crowdin or Crowdin Enterprise account and create a project.
2. Add the project name, source language, visibility and target languages. In our case, we’ll have English as the source language and French and Spanish as the target languages.
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 Editor, using built-in translation tools such as translation memory and glossary management.
6. Proofreaders can review the translated content and provide feedback or approve it.
7. Once translations are completed, you can download the translated files and use them in your website.

## Astro Site Preparation

Astro is a comprehensive web development tool for building fast websites focusing on content.
Let’s initialize a new Astro site:

```bash
# create a new project with npm
npm create astro@latest

# create a new project with pnpm
pnpm create astro@latest

# create a new project with yarn
yarn create astro
```

This will prompt you to enter a project name and select a template. For this tutorial, we’ll use the `blog` template and TypeScript as the language.

Then, organize your translations within the [Astro’s publicDir](https://docs.astro.build/en/reference/configuration-reference/#publicdir), in the `locales` directory. In the example below, we show a simple use case of implementing language sub-paths in Astro using a JSON files to store translations. We will work with three languages, en, fr, and es. In this case, you might have the following locale structure:


```
public
└── locales
    ├── en
    |   └── translation.json
    └── fr
    |   └── translation.json
    └── es
        └── translation.json
```


The translation files will have the following structure:

``public/locales/en/translation.json``:

```json
{
  "nav.home": "Home"`,
  "nav.blog": "Blog",
  "nav.about": "About"
}
```

``public/locales/fr/translation.json``:

```json
{
  "nav.home": "Page d'Accueil",
  "nav.blog": "Blogue",
  "nav.about": "À propos de"
}
```

``public/locales/es/translation.json``:

```json
{
  "nav.home": "Página Principal",
  "nav.blog": "Blog",
  "nav.about": "Acerca de"
}
```
It can be either a plain or nested JSON file depending on your needs. The filename should be the same for all languages. The only difference is the language code in the path.

## Crowdin CLI Configuration
In Astro, you can incorporate [Crowdin CLI](https://crowdin.github.io/crowdin-cli/) in your project to:

- Automate the process of updating your source files in your Crowdin project
- Download translations from Crowdin and automatically save them in the correct locations
- Upload all your existing translations to Crowdin in minutes
The easiest way to install the Crowdin CLI is to use npm:
```
npm install -g @crowdin/cli
```
Visit the [official CLI documentation](https://crowdin.github.io/crowdin-cli/installation) to explore other installation options.

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

```bash
crowdin init
```

You’ll be prompted to enter your Crowdin Project ID and your Personal Access Token. It will generate the `crowdin.yml` file in the root directory of your project.

To set up the Crowdin CLI for your Astro project, you need to add the following configuration to the `crowdin.yml` file:

```yml
"project_id": "project-id"
"api_token": "personal-access-token"

"base_path": "."
"preserve_hierarchy": true
"base_url": "https://api.crowdin.com" # https://{organization-name}.api.crowdin.com for Crowdin Enterprise

"files": [
  {
    "source": "/public/locales/en/translation.json", # Source language file pattern
    "translation": "/public/locales/%two_letters_code%/translation.json"  # Translation files pattern
  }
]
```

It’s recommended to use [environment variables](https://developer.crowdin.com/configuration-file/#api-credentials-from-environment-variables) for referencing the token in your `crowdin.yml` file:
```yml
"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
```

## VCS (Git) Integrations
Crowdin provides VCS (version control systems) integrations for different platforms including GitHub, GitLab, Bitbucket, Azure Repos and other platforms.

- GitHub: supports various GitHub workflows, such as pull request and push notifications, branch updates, and automatic commits.
- GitLab: allows you to synchronize your source and translation files with your GitLab repository, as well as manage your project languages and track the translation progress.
- Bitbucket: allow you to automate updating your source and translation files with your Bitbucket repository.
- Azure Repos: allows you to synchronize your source and translation files with your Azure Repos repository

You can also use the [Crowdin GitHub Action](https://github.com/marketplace/actions/crowdin-action) to automatically manage and synchronize localization resources with your Crowdin project using GitHub workflows.

## 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.

Let’s connect the previously created JSON files with the Astro project using the [astro-i18next](https://github.com/yassinedoghri/astro-i18next) package.

To use the `astro-i18next` package, you need to install it first:
```bash
# npm
npm install astro-i18next

# yarn
yarn add astro-i18next

# pnpm
pnpm add astro-i18next
```
After installing the package, you can start using it to internationalize your project. To do this, you need to add `astro-i18next` to your `astro.config.mjs`:
```typescript
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';

import astroI18next from  'astro-i18next';

export default defineConfig({
  site: 'https://example.com',
  integrations: [mdx(), sitemap(), astroI18next()],
});
```
Configure `astro-i18next` in your `astro-i18next.config.mjs` file:

```typescript
/** @type {import('astro-i18next').AstroI18nextConfig} */
export default {
  defaultLocale: "en",
  locales: ["en", "fr", "es"],
};
```
Next, we need to use the `t()` function available in the `astro-i18next` package to translate the header link titles, for example:

```html
---
import HeaderLink from './HeaderLink.astro';
import { SITE_TITLE } from '../consts';
import i18next, { t } from 'i18next';

const lang = i18next.language;
const base = lang === 'en' ? '' : `/${lang}`;
---

<header>
  <h2>
    {SITE_TITLE}
  </h2>
  <nav>
    <HeaderLink href={`${base}/`}>{ t('nav.home') }</HeaderLink>
    <HeaderLink href={`${base}/blog`}>{ t('nav.blog') }</HeaderLink>
    <HeaderLink href={`${base}/about`}>{ t('nav.about') }</HeaderLink>
    <HeaderLink href="https://twitter.com/astrodotbuild" target="_blank">Twitter</HeaderLink>
    <HeaderLink href="https://github.com/withastro/astro" target="_blank">GitHub</HeaderLink>
  </nav>
</header>
```

Note that we use the `i18next.language` variable to get the current language in order to build the base path for header links. The t() function is used to translate the text.

The package also provides a language switcher component that you can use to switch between languages. To use it, you need to import the `LanguageSelector` component from the `astro-i18next` package. Let’s add it to the `src/components/Footer.astro` component:
```html
---
import { LanguageSelector } from 'astro-i18next/components';
---

<footer>
  <LanguageSelector showFlag={true} />
</footer>
```
Create localized pages using the generate command:

```bash
npx astro-i18next generate
```

You're all set! Now we can run the project and see the results:

```bash
npm run dev
```

You’re all set! Now we can run the project and see the results:
Go to the project in a web browser (http://localhost:3000) and try to change the language 🚀

The localized pages will be available at the following URLs:

- http://localhost:3000 - English
- http://localhost:3000/es - Spanish
- http://localhost:3000/fr - French
Check out a minimalistic Astro web application on [GitHub](https://github.com/yassinedoghri/astro-i18next/tree/beta/examples).

## Connecting Crowdin in an Astro Context
Connecting Crowdin to Astro is easy using APIs provided by Crowdin. To integrate Crowdin with Astro, follow these steps:

- 
Create a project in Crowdin and set up your translation workflow.

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

Here’s an example of using Crowdin to manage translations in 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.

- 
To switch between languages, use the `lang` parameter in your Astro routes. For example, when a user visits `/es/blog`, the API will retrieve the Spanish translations. If the user visits `/fr/blog`, 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. Visit the [Astro documentation](https://docs.astro.build/en/recipes/i18n/) to learn more about i18n in Astro.

## 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: Take advantage of 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 performance of the integration between Crowdin and Astro to ensure that it performs well 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, you can streamline the localization process, and the result will be a web application accessible to a diverse global audience.
[Start a free 14-day trial](https://accounts.crowdin.com/register) today to make your company multilingual with Crowdin.