{"id":15771815,"url":"https://github.com/jlarmstrongiv/astro-i18n-aut","last_synced_at":"2025-05-16T09:05:38.087Z","repository":{"id":173531319,"uuid":"650896154","full_name":"jlarmstrongiv/astro-i18n-aut","owner":"jlarmstrongiv","description":"The i18n integration for Astro 🧑‍🚀","archived":false,"fork":false,"pushed_at":"2025-05-14T11:41:44.000Z","size":1070,"stargazers_count":165,"open_issues_count":2,"forks_count":13,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-14T12:51:13.669Z","etag":null,"topics":["astro","astro-component","astro-i18n-aut","astro-integration","astrojs","defaultlang","defaultlanguage","defaultlocale","i18n","languages","locales"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/astro-i18n-aut","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlarmstrongiv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-08T03:40:53.000Z","updated_at":"2025-05-14T11:41:48.000Z","dependencies_parsed_at":"2023-07-18T05:31:13.514Z","dependency_job_id":"998a7b72-5327-4dc9-9fbe-78894d38a8a8","html_url":"https://github.com/jlarmstrongiv/astro-i18n-aut","commit_stats":{"total_commits":372,"total_committers":3,"mean_commits":124.0,"dds":"0.44892473118279574","last_synced_commit":"62df673192b3b0a6e4202e8f21bee9670d484993"},"previous_names":["jlarmstrongiv/astro-i18n-aut"],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlarmstrongiv%2Fastro-i18n-aut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlarmstrongiv%2Fastro-i18n-aut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlarmstrongiv%2Fastro-i18n-aut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlarmstrongiv%2Fastro-i18n-aut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlarmstrongiv","download_url":"https://codeload.github.com/jlarmstrongiv/astro-i18n-aut/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astro","astro-component","astro-i18n-aut","astro-integration","astrojs","defaultlang","defaultlanguage","defaultlocale","i18n","languages","locales"],"created_at":"2024-10-04T15:05:17.915Z","updated_at":"2025-05-16T09:05:33.078Z","avatar_url":"https://github.com/jlarmstrongiv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `astro-i18n-aut` The i18n integration for Astro 🧑‍🚀\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/jlarmstrongiv/astro-i18n-aut#readme\" target=\"_blank\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/jlarmstrongiv/astro-i18n-aut/main/logos/astro-i18n-aut-dark.svg\"\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/jlarmstrongiv/astro-i18n-aut/main/logos/astro-i18n-aut-light.svg\"\u003e\n      \u003cimg alt=\"astro-i18n-aut\" src=\"https://raw.githubusercontent.com/jlarmstrongiv/astro-i18n-aut/HEAD/logos/astro-i18n-aut-light.svg\" width=\"400\" height=\"225\" style=\"max-width: 100%;\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Built with ❤️ for all Astro crewmates 🧑‍🚀\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/astro-i18n-aut\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/astro-i18n-aut.svg\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n  \u003c!-- https://github.com/astro-i18n-aut/astro-i18n-aut/releases --\u003e\n  \u003ca href=\"https://www.npmjs.com/package/astro-i18n-aut?activeTab=versions\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/astro-i18n-aut.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/astro-i18n-aut.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Motivation\n\nProvide an internationalization (i18n) integration for Astro that:\n\n- Supports the `defaultLocale`\n- Avoids template file duplication\n- Is adapter agnostic\n- Is UI framework agnostic\n- Is compatible with [`@astrojs/sitemap`](https://www.npmjs.com/package/@astrojs/sitemap)\n\n## Quick start\n\n### Install\n\nInstall via [npm](https://www.npmjs.com/package/astro-i18n-aut):\n\n```shell\nnpm install astro-i18n-aut\n```\n\n### Configure\n\nIn your Astro [config](https://docs.astro.build/en/guides/configuring-astro/#supported-config-file-types) file:\n\n```ts\nimport { defineConfig } from \"astro/config\";\nimport { i18n, filterSitemapByDefaultLocale } from \"astro-i18n-aut/integration\";\nimport sitemap from \"@astrojs/sitemap\";\n\nconst defaultLocale = \"en\";\nconst locales = {\n  en: \"en-US\", // the `defaultLocale` value must present in `locales` keys\n  es: \"es-ES\",\n  fr: \"fr-CA\",\n};\n\nexport default defineConfig({\n  site: \"https://example.com/\",\n  trailingSlash: \"always\",\n  build: {\n    format: \"directory\",\n  },\n  integrations: [\n    i18n({\n      locales,\n      defaultLocale,\n    }),\n    sitemap({\n      i18n: {\n        locales,\n        defaultLocale,\n      },\n      filter: filterSitemapByDefaultLocale({ defaultLocale }),\n    }),\n  ],\n});\n```\n\nIn your `.gitignore` file:\n\n```gitignore\nastro_tmp_pages_*\n```\n\n### Usage\n\nNow 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:\n\n- `/about/`\n- `/es/about/`\n- `/fr/about/`\n\nIf you have enabled `redirectDefaultLocale` (`true` by default), redirects will be:\n\n- `/en/about/` =\u003e `/about/`\n\nPlease 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`](https://www.npmjs.com/package/@astrojs/sitemap).\n\nThe Astro frontmatter and page content is re-run for every translated page. For example, the `Astro.url.pathname` will be:\n\n- `/about/`\n- `/es/about/`\n- `/fr/about/`\n\nIt is up to you to detect which language is being rendered. You can use Astro [content collections](https://docs.astro.build/en/guides/content-collections/) or any i18n UI framework, such as [`react-i18next`](https://www.npmjs.com/package/react-i18next), for your translations. Here is a pure `Hello World` example:\n\n```astro\n---\nimport { getLocale } from \"astro-i18n-aut\";\nimport Layout from \"../layouts/Layout.astro\";\n\nconst locale = getLocale(Astro.url);\n\nlet title: string;\nswitch (locale) {\n  case \"es\":\n    title = \"¡Hola Mundo!\";\n    break;\n  case \"fr\":\n    title = \"Bonjour Monde!\";\n    break;\n  default:\n    title = \"Hello World!\";\n}\n---\n\n\u003cLayout title={title}\u003e\n  \u003ch1\u003e{title}\u003c/h1\u003e\n\u003c/Layout\u003e\n```\n\nSeveral helper functions are included to make handling locales easier.\n\n### Astro config options\n\nPlease see the official Astro docs for more details:\n\n- [`site`](https://docs.astro.build/en/reference/configuration-reference/#site)\n- [`trailingSlash`](https://docs.astro.build/en/reference/configuration-reference/#trailingslash)\n- [`format`](https://docs.astro.build/en/reference/configuration-reference/#buildformat)\n\nYou must set either:\n\n- ```js\n  {\n    site: \"https://example.com/\",\n    trailingSlash: \"always\",\n    build: {\n      format: \"directory\",\n    },\n  }\n  ```\n\n- ```js\n  {\n    site: \"https://example.com\",\n    trailingSlash: \"never\",\n    build: {\n      format: \"file\",\n    },\n  }\n  ```\n\nAll these options are related and must be set together. They affect whether your urls are:\n\n- `/about/`\n- `/about`\n\nIf you choose `/about/`, then `/about` will 404 and vice versa.\n\n### Integration options\n\n- `locales`: A record of all language locales.\n- `defaultLocale`: The default language locale. The value must present in `locales` keys.\n- `redirectDefaultLocale` - Assuming the `defaultLocale: \"en\"`, whether `/en/about/` redirects to `/about/` (default: `308`).\n- `include`: Glob pattern(s) to include (default: `[\"pages/**/*\"]`).\n- `exclude`: Glob pattern(s) to exclude (default: `[\"pages/api/**/*\"]`).\n\n### Compatibility\n\n#### Page file types\n\nOther Astro page file types:\n\n- ✅ `.astro`\n- ❌ `.md`\n- ❌ `.mdx` (with the MDX Integration installed)\n- ❌ `.html`\n- ❌ `.js` / `.ts` (as endpoints)\n\ncannot be translated. If you choose to use them in the `pages` directory, please add them to the ignore glob patterns. For example:\n\n```js\n[\"pages/api/**/*\", \"pages/**/*.md\"];\n```\n\n#### Excluding pages\n\nIn Astro, the [docs](https://docs.astro.build/en/core-concepts/routing/#excluding-pages) state:\n\n\u003e You can exclude pages or directories from being built by prefixing their names with an underscore (_). Files with the _ prefix won’t be recognized by the router and won’t be placed into the dist/ directory.\n\u003e\n\u003e You can use this to temporarily disable pages, and also to put tests, utilities, and components in the same folder as their related pages.\n\nUnfortunately, this [excluding pages](https://docs.astro.build/en/core-concepts/routing/#excluding-pages) feature is not supported. Please only keep pages in your pages directory.\n\nYou can still exclude pages prefixed with an underscore (`_`) by adding `pages/**/_*` to the ignore glob patterns:\n\n```js\n[\"pages/api/**/*\", \"pages/**/_*\"];\n```\n\n#### Markdown\n\nFor `.md` and `.mdx`, use Astro [Content](https://docs.astro.build/en/guides/content-collections/#organizing-with-subdirectories) [Collections](https://docs.astro.build/en/recipes/i18n/#use-collections-for-translated-content).\n\nWith 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:\n\n```\n.\n└── astro-project/\n    └── src/\n        ├── pages/\n        │   └── blog/\n        │       ├── index.astro\n        │       └── [id].astro\n        └── content/\n            └── blog/\n                ├── en/\n                │   ├── post-1.md\n                │   └── post-2.md\n                ├── es/\n                │   ├── post-1.md\n                │   └── post-2.md\n                └── fr/\n                    ├── post-1.md\n                    └── post-2.md\n```\n\n#### UI frameworks\n\nAstro does not support `.tsx` or `.jsx` as page file types.\n\nFor UI frameworks like React and Vue, use them how you [normally](https://docs.astro.build/en/core-concepts/framework-components/) would with Astro by importing them as components.\n\nFeel free to pass the translated content `title={t('title')}` or locale `locale={locale}` as props.\n\n#### Endpoints\n\nBy default, all pages in `pages/api/**/*` are ignored.\n\nFor `.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.\n\n## License\n\nMIT Licensed\n\n## Contributing\n\nPRs welcome! Thank you for your help. Read more in the [contributing guide](https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/CONTRIBUTING.md) for reporting bugs and making PRs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlarmstrongiv%2Fastro-i18n-aut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlarmstrongiv%2Fastro-i18n-aut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlarmstrongiv%2Fastro-i18n-aut/lists"}