Internationalization (i18n)

The starlight-tags plugin integrates with Starlight’s i18n system and provides built-in translations for:

• English (en)
• French (fr)
• Spanish (es)
• German (de)

Translated UI Strings

The plugin uses the following translation keys for its UI components:

Key	English Default
starlightTags.totalTags	Total Tags
starlightTags.tagsApplied	Tags Applied
starlightTags.tagCloud	Tag Cloud
starlightTags.alphabeticalIndex	Alphabetical Index
starlightTags.allTags	All Tags
starlightTags.page	page
starlightTags.pages	pages
starlightTags.pageTags	Tags:
starlightTags.taggedPrefix	Tagged:
starlightTags.relatedTags	Related Tags
starlightTags.pagesWithTag	Pages with this tag
starlightTags.related	related
starlightTags.path	Path:
starlightTags.pagination.label	Pagination
starlightTags.pagination.page	Page
starlightTags.pagination.of	of
starlightTags.pagination.previous	Previous page
starlightTags.pagination.next	Next page
starlightTags.pagination.item	tagged item
starlightTags.pagination.items	tagged items
starlightTags.popularTags	Popular Tags
starlightTags.viewAllTags	View all tags

Localized Tag Labels and Descriptions

In addition to UI strings, you can localize the tag labels and descriptions themselves in your tags.yml file. This allows tag names to appear in the user’s language.

Simple Format (Single Language)

For single-language sites, use simple strings:

tags:
  components:
    label: "Components"
    description: "UI components and their usage patterns"

Localized Format (Multiple Languages)

For multilingual sites, provide translations as an object with locale keys:

tags:
  components:
    label:
      en: "Components"
      fr: "Composants"
      es: "Componentes"
      de: "Komponenten"
    description:
      en: "UI components and their usage patterns"
      fr: "Composants d'interface utilisateur et leurs modèles d'utilisation"
      es: "Componentes de interfaz de usuario y sus patrones de uso"
      de: "UI-Komponenten und ihre Verwendungsmuster"
    color: "#14b8a6"
    icon: "🧩"

Mixed Format

You can mix both formats in the same file. Tags with simple string labels will display the same text for all locales:

tags:
  # Localized tag
  components:
    label:
      en: "Components"
      fr: "Composants"
    description:
      en: "UI components"
      fr: "Composants d'interface"

  # Simple string (same for all locales)
  api:
    label: "API"
    description: "API reference documentation"

Fallback Behavior

When a locale is not found in the translation record, the plugin follows this fallback chain:

1. Requested locale - e.g., fr for French pages
2. Default locale - typically en
3. First available value - if neither locale exists
4. Tag ID - as a last resort for labels

Customizing Translations

You can override any translation by adding entries to your src/content/i18n/ files. This allows you to customize the labels or add support for additional languages.

Step 1: Set Up i18n Content Collection

If you haven’t already, add the i18n collection to your src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

Step 2: Create Translation Files

Create JSON files in src/content/i18n/ for each language you want to customize:

src/content/i18n/en.json

{
  "starlightTags.totalTags": "Topics",
  "starlightTags.tagsApplied": "Total References"
}

src/content/i18n/fr.json

{
  "starlightTags.totalTags": "Catégories",
  "starlightTags.tagsApplied": "Références totales"
}

Adding New Languages

To add a language not included in the plugin’s built-in translations, create a translation file with all the keys:

src/content/i18n/ja.json

{
  "starlightTags.totalTags": "タグ総数",
  "starlightTags.tagsApplied": "適用されたタグ",
  "starlightTags.tagCloud": "タグクラウド",
  "starlightTags.alphabeticalIndex": "アルファベット順索引",
  "starlightTags.allTags": "すべてのタグ",
  "starlightTags.page": "ページ",
  "starlightTags.pages": "ページ",
  "starlightTags.pageTags": "タグ：",
  "starlightTags.taggedPrefix": "タグ付き：",
  "starlightTags.relatedTags": "関連タグ",
  "starlightTags.pagesWithTag": "このタグのページ",
  "starlightTags.related": "関連",
  "starlightTags.path": "パス：",
  "starlightTags.pagination.label": "ページネーション",
  "starlightTags.pagination.page": "ページ",
  "starlightTags.pagination.of": "/",
  "starlightTags.pagination.previous": "前のページ",
  "starlightTags.pagination.next": "次のページ",
  "starlightTags.pagination.item": "タグ付きアイテム",
  "starlightTags.pagination.items": "タグ付きアイテム"
}

How It Works

The plugin automatically detects the current locale from Starlight’s routing and displays the appropriate translations. When a translation key is not found for a locale, it falls back to the English default.

Locale-Aware URLs

All tag-related URLs are automatically localized:

• Default locale: /tags/authentication/
• French: /fr/tags/authentication/
• German: /de/tags/authentication/

This works seamlessly with Starlight’s defaultLocale: 'root' configuration, where the default language has no URL prefix.