Internationalisation

Xingluo est livré avec un support UI bilingue (zh-CN / en), utilisant la stratégie de routage prefixDefaultLocale: false afin que la langue par défaut n’ait pas de préfixe d’URL.

Stratégie de routage

La configuration i18n d’Astro (voir astro.config.ts) :

ts
i18n: {
  locales: ["zh-cn", "en"],
  defaultLocale: "zh-cn",
  routing: { prefixDefaultLocale: false },
}

Important : prefixDefaultLocale: false ne génère pas automatiquement de copies de page localisées — vous devez maintenir manuellement les routes miroir [locale]/.

Approche de Xingluo :

Pages racines = langue par défaut (zh-cn), pas de préfixe d’URL, ex. /posts/welcome/
src/pages/[locale]/ reflète toutes les pages ; getStaticPaths utilise getLocaleParams() pour générer uniquement les locales non par défaut, ex. /en/posts/welcome/
Les pages miroir sont également des wrappers fins, réutilisant le même composant View pour la logique de rendu

Résolution de locale

Les composants View utilisent Astro.currentLocale pour la résolution automatique :

Pages racine → zh-cn
Pages segment [locale] → en (ou autres locales non par défaut)

Aucune vérification de chemin n’est nécessaire au niveau du composant ; useTranslations(locale) récupère les chaînes correspondantes directement.

Structure du module i18n

src/i18n/ :

Fichier	Responsabilité
`index.ts`	`import.meta.glob("./lang/*.ts", {eager:true})` charge les langues ; exporte `DEFAULT_LOCALE`, `LOCALES`, `useTranslations(locale)`, `tplStr`
`types.ts`	Interface `UIStrings` complète (toutes les chaînes à localiser)
`routing.ts`	`getLocalePrefix`, `withLocale(path, locale)`, `parseLocaleFromPath(pathname)`
`staticPaths.ts`	`NON_DEFAULT_LOCALES`, `getLocaleParams()`
`format.ts`	`tplStr(template, vars)` — remplacement de placeholder `{{key}}`
`lang/zh-cn.ts`	Chinois simplifié (par défaut)
`lang/en.ts`	Anglais

Structure UIStrings

L’interface UIStrings définit toutes les chaînes UI à localiser, organisées en groupes :

nav : navigation (accueil/articles/tags/à propos/archives/recherche/rss)
post : article (date, partage, tags, retour, édition, TOC, copie de code, lightbox d’image, etc.)
pagination : pagination
home : page d’accueil (liens sociaux, à la une, récents)
archives : archives (comptages, mois)
footer : pied de page (copyright)
pages : titres et descriptions des pages
a11y : étiquettes d’accessibilité
languageSwitcher : sélecteur de langue
notFound : 404
comments : section des commentaires

Chaînes de modèle

Les chaînes avec des placeholders utilisent {{key}}, remplacées via tplStr :

ts
import { tplStr } from "@/i18n";

// archives.postCount = "{{count}} articles"
tplStr(t.archives.postCount, { count: 5 }); // "5 articles"

Déclarations SEO multilingues

La balise <head> de Layout.astro produit :

<link rel="alternate" hreflang="..." href="..."> pour chaque langue
x-default pointe vers la langue par défaut
L’intégration sitemap active la configuration i18n pour générer automatiquement hreflang
Les articles dans une locale non par défaut ont un canonical pointant vers l’original dans la locale par défaut (pour éviter les pénalités de contenu en double ; voir SEO)

Ajouter une langue

Exemple : ajouter le japonais ja :

astro.config.ts : ajoutez "ja" à i18n.locales et le mappage "ja": "ja-JP" à i18n.locales du sitemap
src/i18n/lang/ : créez ja.ts exportant un UIStrings complet (copiez en.ts et traduisez)
src/i18n/staticPaths.ts : NON_DEFAULT_LOCALES inclut automatiquement ja (calculé à partir de LOCALES)
src/pages/[locale]/ : les pages miroir génèrent automatiquement la version ja (getLocaleParams la couvre)
Sélecteur de langue : ajoutez "ja": "日本語" à languageSwitcher.names dans zh-cn.ts et en.ts

Traduction au niveau du contenu

Xingluo prend en charge le contenu multilingue des articles via les champs frontmatter locale et translationKey.

Utilisation de base

Article en langue par défaut : placez-le dans src/content/posts/<slug>.md, définissez translationKey comme identifiant de groupe :

yaml
# src/content/posts/welcome.md
---
title: "欢迎来到星罗"
locale: zh-cn
translationKey: welcome-to-xingluo
tags: [公告, Astro]
---

Traduction : placez-la dans un sous-répertoire de langue src/content/posts/<locale>/<slug>.md, en utilisant le même translationKey :

yaml
# src/content/posts/en/welcome.md
---
title: "Welcome to Xingluo"
locale: en
translationKey: welcome-to-xingluo
tags: [announcement, Astro]
---

Structure du répertoire


src/content/posts/
├── welcome.md              # Langue par défaut (zh-cn)
├── en/
│   └── welcome.md          # Traduction anglaise
├── ja/
│   └── welcome.md          # Traduction japonaise
└── another-post.md         # Article indépendant (pas de translationKey)

Les noms des sous-répertoires de langue doivent correspondre aux codes de langue dans i18n.locales de astro.config.ts
Les sous-répertoires de langue sont filtrés du slug d’URL (ex. /posts/welcome/, pas /posts/en/welcome/)
Les articles sans translationKey sont indépendants et ne sont pas liés entre les langues

Comportement de routage

Scénario	Comportement
Accès à la locale par défaut d’un article `zh-cn`	Affiche l’original dans la langue par défaut
Locale non par défaut avec une traduction	Affiche la traduction correspondante
Locale non par défaut sans traduction	Revient à l’original dans la langue par défaut (contenu identique, canonical protège le SEO)

Déduplication des listes

Les pages de liste (accueil, liste d’articles, tags, archives, RSS) utilisent getPostsForLocale pour sélectionner des articles représentatifs par langue : chaque groupe de traduction n’affiche qu’une seule carte dans la langue cible, empêchant les entrées en double pour le même sujet.

canonical et SEO

A une traduction indépendante : le canonical pointe vers l’URL propre de la traduction, indexable séparément par les moteurs de recherche
Pas de traduction (repli) : le canonical pointe vers l’original dans la langue par défaut, évitant les pénalités de contenu en double
Les déclarations hreflang couvrent toutes les langues, informant les moteurs de recherche des relations entre les versions linguistiques

See SEO.