AstroPaper I18n

AstroPaper I18n is a fork of the AstroPaper blog theme that adds full internationalization (i18n) support, including right-to-left (RTL) layout direction, to Astro-based static sites.

What is AstroPaper I18n?

AstroPaper I18n is a static blog theme for Astro, forked from the popular AstroPaper theme by satnaing and maintained by yousef8. It takes markdown content organized by locale folders and translation files, and produces a multilingual static blog with localized UI, sitemaps, RSS feeds, and OG images. The theme runs on the Astro framework and uses Astro's built-in i18n routing.

Unlike the original AstroPaper, this fork does not modify the theme's UI; it only layers i18n features on top. The author, a native Arabic speaker, specifically ensured that the i18n integration supports RTL languages such as Arabic and Persian. The project aims to stay synchronized with the upstream AstroPaper repository.

Key Features

AstroPaper I18n adds i18n and RTL support while inheriting everything from the original AstroPaper theme. Below are the concrete features documented in the repository.

• Full RTL/LTR support — The UI is direction-agnostic and keeps a consistent layout for both LTR and RTL languages, with a direction option accepting rtl, ltr, or auto.
• Type-safe translations — Locale files in src/i18n/locales are TypeScript modules typed as I18nStrings, giving compile-time checks for missing or misspelled translation keys.
• Language switcher — A language picker is included, with locale display names defined in src/i18n/config.ts.
• Localized sitemap — Uses @astrojs/sitemap to generate sitemaps with i18n support.
• Localized RSS feeds — Uses @astrojs/rss to produce i18n-aware RSS feeds.
• Localized OG image generation — OG images are generated per locale, with a caveat: satori does not support RTL languages, so RTL OG images may have layout issues.
• Unit testing with Vitest — Ships with Vitest setup; run npm test, npm run test:watch, or npm run coverage for test reports.
• Content collections for translations — Blog content lives in locale folders under src/content/blog, and the about page has its own content collection with files named about.<locale>.md.

Who is it for?

AstroPaper I18n is aimed at anyone who wants a lightweight, SEO-friendly blog that serves content in multiple languages without abandoning the AstroPaper design.

• Multilingual bloggers — Publish markdown posts per language by creating a folder for each locale key under src/content/blog, and the theme handles localized URLs, dates, and numbers.
• Arabic and Persian site owners — Get a full RTL layout out of the box, something the original AstroPaper lacks.
• Developers building internationalized Astro sites — Use the type-safe i18n config, locale profiles, and unit tests to extend the theme with new languages.
• AstroPaper users needing i18n — Adopt this fork instead of hand-rolling i18n onto the original theme, since the fork preserves the upstream UI.

What can you do with AstroPaper I18n?

• Arabic blogger: Set direction: "rtl" and langTag: "ar-EG" for your locale to get a full right-to-left blog with localized dates and numbers.
• Multi-language site owner: Add an English and a Spanish locale by creating en.ts and es.ts translation files, then organizing posts under src/content/blog/en and src/content/blog/es.
• Open-source maintainer: Use the included Vitest commands to run unit tests on i18n utilities and configurations, and contribute fixes for the documented known issues.

How does AstroPaper I18n work?

Adding a new language follows a four-step workflow documented in the README.

1. Create a translation file named with the locale key (for example, es.ts for Spanish) in src/i18n/locales, exporting an I18nStrings object.
2. Register the locale in src/i18n/config.ts with its name, messages, BCP-47 language tag, layout direction, and Google font used for OG images.
3. Add an about page for the locale as about.<locale>.md in src/content/about.
4. Place markdown posts in a folder named after the locale key under src/content/blog, then restart the dev server.

Pros and cons

• Pros:

  • Adds i18n without altering the original AstroPaper UI.
  • Full RTL support for Arabic, Persian, and other RTL languages.
  • Type-safe translation keys help catch errors during development.
  • Maintains sync with the upstream AstroPaper theme.
  • Comprehensive i18n for sitemaps, RSS feeds, and OG images.

• Cons:

  • Screen reader mode styling is currently broken (documented as a known issue).
  • OG images for RTL languages may have layout issues because satori lacks RTL support.

FAQ

Does AstroPaper I18n support RTL languages?

Yes. Each locale profile accepts a direction value of rtl, ltr, or auto, and the UI is designed to look consistent in both directions. The author built the fork specifically with native Arabic support and it also works for Persian.

How do I add a new language?

Create a TypeScript file named with the locale key in src/i18n/locales, define its profile in src/i18n/config.ts, add an about page named about.<locale>.md, and put blog posts under src/content/blog/<locale>. Restart the dev server to see the changes.

Is the i18n implementation type-safe?

Yes. Translation files are typed as I18nStrings from @i18n/types, so missing or misspelled keys are caught at build time. The theme also includes Vitest unit tests for i18n configurations and utilities.

Does this fork keep the original AstroPaper design?

Yes. The README explicitly states that the fork does not modify the original theme's UI; it solely adds internationalization. It also includes all features of the original AstroPaper theme.

What known limitations does it have?

The README lists two known issues: screen reader mode styling is broken and needs fixes, and OG image generation for RTL languages has layout problems because satori does not support RTL. Both are open for contributions.