{"id":14963008,"url":"https://github.com/openscript-ch/gatsby-plugin-i18n-l10n","last_synced_at":"2025-10-25T00:31:47.353Z","repository":{"id":39082351,"uuid":"451064653","full_name":"openscript-ch/gatsby-plugin-i18n-l10n","owner":"openscript-ch","description":"Gatsby I18n Plugin 🌐, which let you translate pages, content and the url or slugs of pages. Batteries 🔋 included.","archived":false,"fork":false,"pushed_at":"2024-10-26T07:42:51.000Z","size":6494,"stargazers_count":19,"open_issues_count":13,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-30T00:35:51.425Z","etag":null,"topics":["gatsby","gatsby-plugin","gatsbyjs","i18n","internationalization","localization","react-intl"],"latest_commit_sha":null,"homepage":"https://www.gatsbyjs.com/plugins/gatsby-plugin-i18n-l10n","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/openscript-ch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2022-01-23T10:02:32.000Z","updated_at":"2024-09-10T14:03:20.000Z","dependencies_parsed_at":"2022-07-13T09:20:34.572Z","dependency_job_id":"49d65c36-bcbd-419e-90f0-4b5898fa3ad7","html_url":"https://github.com/openscript-ch/gatsby-plugin-i18n-l10n","commit_stats":{"total_commits":312,"total_committers":5,"mean_commits":62.4,"dds":"0.40384615384615385","last_synced_commit":"1df690cf1bc6cdaa9abb963c7f8f16b24da5674c"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Fgatsby-plugin-i18n-l10n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Fgatsby-plugin-i18n-l10n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Fgatsby-plugin-i18n-l10n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Fgatsby-plugin-i18n-l10n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openscript-ch","download_url":"https://codeload.github.com/openscript-ch/gatsby-plugin-i18n-l10n/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238053514,"owners_count":19408699,"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":["gatsby","gatsby-plugin","gatsbyjs","i18n","internationalization","localization","react-intl"],"created_at":"2024-09-24T13:30:54.333Z","updated_at":"2025-10-25T00:31:46.920Z","avatar_url":"https://github.com/openscript-ch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gatsby-plugin-i18n-l10n\n\n[![Codecov](https://img.shields.io/codecov/c/github/openscript-ch/gatsby-plugin-i18n-l10n)](https://app.codecov.io/gh/openscript-ch/gatsby-plugin-i18n-l10n) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/openscript-ch/gatsby-plugin-i18n-l10n/ci.yml?branch=main)](https://github.com/openscript-ch/gatsby-plugin-i18n-l10n/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/gatsby-plugin-i18n-l10n)](https://www.npmjs.com/package/gatsby-plugin-i18n-l10n) [![npm](https://img.shields.io/npm/dm/gatsby-plugin-i18n-l10n)](https://www.npmjs.com/package/gatsby-plugin-i18n-l10n)\n\nProviding i18n and l10n to Gatsby. Besides translating pages and Markdown files, you can also translate the slugs and paths and still link between translated sibling pages. Batteries like a language switcher component are included. The plugin is written in Typescript, has some tests and has only one peer dependency:\n\n- [**react-intl**](https://formatjs.io/docs/react-intl/): Wrapping the pages with a provider, which makes translation available throughout the app.\n\n## Features\n\n- **Generates translated** versions of **pages**.\n  - For example, if you have a page `src/pages/about.tsx` and the languages `en-US` and `de-CH` configured, then it will create an `en-US` and `de-CH` version of this page. Via the page context of the translated pages, you get to know the locale.\n- **Adds fields** on MarkdownRemark and Mdx **nodes**.\n- Puts **prefixes** into the page paths, but not when it's the **default locale**.\n- **Picks up locale** from Markdown file names and provides it via custom fields in GraphQL.\n  - It works with `gatsby-transformer-remark` and `gatsby-plugin-mdx`.\n- Makes it easy to **navigate between the translations** of a page.\n- Sets **meta tags** to provide locale information to crawlers and other machines.\n- Provides **useful components** like `\u003cLocalizedLink\u003e` and `\u003cLanguageSwitcher\u003e`.\n- Helps to **translate paths**, while keeping the possibility to navigate between the translations of a page.\n\n## Usage\n\n1. Make sure the packages `\"gatsby\": \"^5.x\"` and `\"react-intl\": \"^6.x\"` are dependencies of your Gatsby project.\n1. Install the plugin with `npm install gatsby-plugin-i18n-l10n` or `yarn add gatsby-plugin-i18n-l10n`.\n1. Load and configure the plugin from your `gatsby-config.js` or `gatsby-config.ts`:\n\n   ```typescript\n   {\n     resolve: `gatsby-plugin-i18n-l10n`,\n     options: {\n       // string: IETF BCP 47 language tag: default locale, which won't be prefixed\n       defaultLocale: `de-CH`,\n       // string: absolute site url\n       siteUrl: `https://example.com`,\n       // locales[]: all locales, which should be available\n       locales: [\n         {\n           // string: IETF BCP 47 language tag of this language\n           locale: `en-US`,\n           // string: prefix for this language, which will be used to prefix the url, if it's not the default locale\n           prefix: `en`,\n           // object: mapping of given urls (by filename) to translated urls, if no mapping exists, given url will be used\n           slugs: {},\n           // object: this messages will be handed over to react-intl and available throughout the website\n           messages: {\n             \"language\": \"English\"\n           },\n         },\n         // another language\n         {\n           locale: `de-CH`,\n           prefix: `de`,\n           slugs: {\n             '/products/': '/produkte/',\n             '/products/#donut-filled-with-jam': '/produkte/#berliner',\n             '/services/software-development/': '/dienstleistungen/softwareentwicklung/'\n           },\n           pageBlacklist: ['/do-not-translate-to-german/'], // If there is a page with the a given path it won't be translated\n           messages: {\n             \"language\": \"Deutsch\"\n           },\n         },\n       ],\n       // omit certain path segments (relative directories)\n       // be careful not to cause path collisions\n       pathBlacklist: [\n         '/pages' // /pages/products/gummibears/ becomes /products/gummibears/\n       ],\n       // set handling of trailing slashes\n       // set it to the same value as for the rest of Gatsby\n       // behaves like https://www.gatsbyjs.com/docs/reference/config-files/gatsby-config/#trailingslash\n       // default: always\n       trailingSlash: 'always'\n     },\n   }\n   ```\n\n### `\u003cLanguageSwitcher\u003e`\n\nWith the built-in `\u003cLanguageSwitcher\u003e` component users can change between the locales. With `resolveLanguageName` prop the language names can be provided to the component.\n\n```jsx\n\u003cLanguageSwitcher resolveLanguageName={(locale) =\u003e intl.formatMessage({ id: `languages.${locale}` })} /\u003e\n```\n\n### `\u003cLocalizedLink\u003e`\n\n`\u003cLocalizedLink\u003e` wraps Gatsby `\u003cLink\u003e` component, thus it should be possible to use it in the same way.\n\n```jsx\n\u003cLocalizedLink to=\"/products/\"\u003eProdukte\u003c/LocalizedLink\u003e\n```\n\nIf the configuration from above is used and the user views this link inside the i18n context `de-CH` the link will lead him to `/de/produkte`.\n\n### `\u003cGenericLocalizedLink\u003e`\n\nWith the built-in `\u003cGenericLocalizedLink\u003e` component it's possible to use other plugins, which modify Gatsbys `\u003cLink\u003e` component. Here is an example with [Gatsby Plugin Transition Link](https://www.gatsbyjs.com/plugins/gatsby-plugin-transition-link/):\n\n```jsx\n\u003cGenericLocalizedLink to=\"/imprint/\"\u003e\n  {(args) =\u003e (\n    \u003cTransitionLink\n      to={args.to}\n      exit={{\n        trigger: ({ exit, node }) =\u003e this.interestingExitAnimation(exit, node),\n        length: 1,\n      }}\n      entry={{\n        delay: 0.6,\n      }}\n    \u003e\n      Go to page 2\n    \u003c/TransitionLink\u003e\n  )}\n\u003c/GenericLocalizedLink\u003e\n```\n\nAnother example with `\u003cAniLink\u003e`:\n\n```jsx\n\u003cGenericLocalizedLink to=\"/imprint\"\u003e\n  {(args) =\u003e (\n    \u003cAniLink fade to={args.to}\u003e\n      Go to Page 4\n    \u003c/AniLink\u003e\n  )}\n\u003c/GenericLocalizedLink\u003e\n```\n\n### `createPage()`\n\nWhen you create pages programmatically with `createPage()` by default the page will only try to set the locale and prefix to the context. With the following options you can instruct the plugin to internationalize the context further:\n\n- `referTranslations: string[]`: Refers translations for given locales.\n- `adjustPath: boolean`: Add locale prefix and replaces slugs.\n\n### GraphQL data layer integration\n\nAll translation messages are sourced to Gatsbys GraphQL data layer with `translation` and `allTranslation`. Here is an example GraphQL query:\n\n```typescript\nexport const query = graphql`\n  query SomePage($locale: String) {\n    pageTitle: translation(locale: { eq: $locale }, key: { eq: \"page.some.title\" }) {\n      message\n    }\n    pageDescription: translation(locale: { eq: $locale }, key: { eq: \"page.some.description\" }) {\n      message\n    }\n  }\n`;\n```\n\n## Development\n\n1. **Clone** the project\n1. **Open** the freshly cloned project with Visual Studio Code and [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).\n1. **Install** the projects dependencies with `npm install`.\n1. **Run** the tests with `npm test`.\n1. **Install** the examples dependencies with `npm run example install`.\n1. **Run** the example project with `npm run example start`.\n\n## Alternatives\n\n- [gatsby-theme-i18n](https://www.gatsbyjs.com/plugins/gatsby-theme-i18n)\n- [gatsby-plugin-i18n](https://github.com/angeloocana/gatsby-plugin-i18n)\n- [gatsby-plugin-intl](https://www.gatsbyjs.com/plugins/gatsby-plugin-intl)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenscript-ch%2Fgatsby-plugin-i18n-l10n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenscript-ch%2Fgatsby-plugin-i18n-l10n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenscript-ch%2Fgatsby-plugin-i18n-l10n/lists"}