Giter Club home page Giter Club logo

astro-i18n-aut's Introduction

astro-i18n-aut The i18n integration for Astro πŸ§‘β€πŸš€

astro-i18n-aut

Built with ❀️ for all Astro crewmates πŸ§‘β€πŸš€

Total Downloads Latest Release License


Motivation

Provide an internationalization (i18n) integration for Astro that:

  • Supports the defaultLocale
  • Avoids template file duplication
  • Is adapter agnostic
  • Is UI framework agnostic
  • Is compatible with @astrojs/sitemap

Quick start

Install

Install via npm:

npm install astro-i18n-aut

Configure

In your Astro config file:

import { defineConfig } from "astro/config";
import { i18n, defaultLocaleSitemapFilter } from "astro-i18n-aut/integration";
import sitemap from "@astrojs/sitemap";

const defaultLocale = "en";
const locales = {
  en: "en-US", // the `defaultLocale` value must present in `locales` keys
  es: "es-ES",
  fr: "fr-CA",
};

export default defineConfig({
  site: "https://example.com/",
  trailingSlash: "always",
  build: {
    format: "directory",
  },
  integrations: [
    i18n({
      locales,
      defaultLocale,
    }),
    sitemap({
      i18n: {
        locales,
        defaultLocale,
      },
      filter: defaultLocaleSitemapFilter({ defaultLocale }),
    }),
  ],
});

In your Astro middleware file:

import { sequence } from "astro/middleware";
import { i18nMiddleware } from "astro-i18n-aut";

const i18n = i18nMiddleware({ defaultLocale: "en" });

export const onRequest = sequence(i18n);

In your .gitignore file:

astro_tmp_pages_*

Usage

Now that you have set up the config, each .astro page will have additional renders with your other languages. For example, src/pages/about.astro will render as:

  • /about/
  • /es/about/
  • /fr/about/

If you have enabled redirectDefaultLocale (true by default) in the integration and middleware, redirects will be:

  • /en/about/ => /about/

Please note that the getStaticPaths() function will only run once. This limitation means that you cannot have translated urls, such as /es/acerca-de/ for /about/. However, it also ensures compatibility with @astrojs/sitemap.

The Astro frontmatter and page content is re-run for every translated page. For example, the Astro.url.pathname will be:

  • /about/
  • /es/about/
  • /fr/about/

It is up to you to detect which language is being rendered. You can use Astro content collections or any i18n UI framework, such as react-i18next, for your translations. Here is a pure Hello World example:

---
import { getLocale } from "astro-i18n-aut";
import Layout from "../layouts/Layout.astro";

const locale = getLocale(Astro.url);

let title: string;
switch (locale) {
  case "es":
    title = "Β‘Hola Mundo!";
    break;
  case "fr":
    title = "Bonjour Monde!";
    break;
  default:
    title = "Hello World!";
}
---

<Layout title={title}>
  <h1>{title}</h1>
</Layout>

Astro config options

Please see the official Astro docs for more details:

You must set either:

  • {
      site: "https://example.com/",
      trailingSlash: "always",
      build: {
        format: "directory",
      },
    }
  • {
      site: "https://example.com",
      trailingSlash: "never",
      build: {
        format: "file",
      },
    }

All these options are related and must be set together. They affect whether your urls are:

  • /about/
  • /about

If you choose /about/, then /about will 404 and vice versa.

Integration options

  • locales: A record of all language locales.
  • defaultLocale: The default language locale. The value must present in locales keys.
  • redirectDefaultLocale - Assuming the defaultLocale: "en", whether /en/about/ redirects to /about/ (default: true).
  • include: Glob pattern(s) to include (default: ["pages/**/*"]).
  • exclude: Glob pattern(s) to exclude (default: ["pages/api/**/*"]).

Other Astro page file types:

  • βœ… .astro
  • ❌ .md
  • ❌ .mdx (with the MDX Integration installed)
  • ❌ .html
  • ❌ .js / .ts (as endpoints)

cannot be translated. If you choose to use them in the pages directory, please add them to the ignore glob patterns. For example, ["pages/api/**/*", "pages/**/*.md"]

Markdown

For .md and .mdx, use Astro Content Collections.

With this library and Astro Content Collections, you can keep your Markdown separate and organized in content, while using pages/blog/index.astro and pages/blog/[slug].astro to render all of your content, even with a defaultLocale! Here is an example folder structure:

.
└── astro-project/
    └── src/
        β”œβ”€β”€ pages/
        β”‚   └── blog/
        β”‚       β”œβ”€β”€ index.astro
        β”‚       └── [id].astro
        └── content/
            └── blog/
                β”œβ”€β”€ en/
                β”‚   β”œβ”€β”€ post-1.md
                β”‚   └── post-2.md
                β”œβ”€β”€ es/
                β”‚   β”œβ”€β”€ post-1.md
                β”‚   └── post-2.md
                └── fr/
                    β”œβ”€β”€ post-1.md
                    └── post-2.md

UI frameworks

Astro does not support .tsx or .jsx as page file types.

For UI frameworks like React and Vue, use them how you normally would with Astro by importing them as components.

Feel free to pass the translated content title={t('title')} or locale locale={locale} as props.

Endpoints

By default, all pages in pages/api/**/* are ignored.

For .ts and .js endpoints, how you handle multiple locales is up to you. As endpoints are not user-facing and there are many different ways to use endpoints, we leave the implementation up to your preferences.

Middleware options

  • defaultLocale - The default language locale. The value must present in locales keys.
  • redirectDefaultLocale - Assuming the defaultLocale: "en", whether /en/about/ redirects to /about/ (default: true).

License

MIT Licensed

Contributing

PRs welcome! Thank you for your help. Read more in the contributing guide for reporting bugs and making PRs.

astro-i18n-aut's People

Contributors

jlarmstrongiv avatar renovate[bot] avatar seanpue avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.