Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


npm package

gatsby-plugin-translate-urls is a Gatsby plugin to translate urls

You ave two choices:

  1. all locales in urls
  • yoursite.com/en
  • yoursite.com/fr
  • yoursite.com/es
  1. locales in urls except the default locale:

You need to set the defaultLocale option

  • yoursite.com
  • yoursite.com/fr
  • yoursite.com/es


  1. Download gatsby-plugin-translate-urls from the NPM registry:
yarn add gatsby-plugin-translate-urls
  1. Create translations files (.js or .json)


  "urls.about": "about",
  "urls.posts": "posts"


  "urls.about": "a-props",
  "urls.posts": "articles"
  1. Add the plugin in your gatsby-config.js file
module.exports = {
  plugins: [
      resolve: "gatsby-plugin-translate-urls",
      options: {
        translations: {
          // import JS or JSON files
          en: require("./src/translations/en.js"),
          fr: require("./src/translations/fr.json"),
        // OPTIONAL
        // To remove the default locale from urls
        defaultLocale: "en"
        // prefix in translations files
        prefix: "urls.", // default: ""
  1. Translate urls in your pages

Most of the time, you only need the TranslatedLink component. It will transform the url passed to to prop.

import React from "react"
import {TranslatedLink} from "gatsby-plugin-translate-urls"

export default () => {
  return <TranslatedLink to="/posts">Posts FR</TranslatedLink>

For most advanced cases or if you want to use the original gatsby link, you can use TranslateUrlsContext to get some useful data:

import React, {useContext} from "react"
import {Link} from "gatsby"
import {TranslateUrlsContext} from "gatsby-plugin-translate-urls"

export default () => {
  const {
    locale, // fr
    locales, // ["en", "fr"]
    originalUrl, // "/about"
    translateUrl // (url(, locale)) => translatedUrl
  } = useContext(TranslateUrlsContext)
  return (
      <Link to={translateUrl(originalUrl)}>About FR</Link>
      <Link to={translateUrl(originalUrl, "en")}>About EN</Link>
      {"All localized /about pages:"}
      {locales.map(lang => <Link key={lang}to={translateUrl(originalUrl, lang)}>About {lang}<)}


  • ⇄ Pull/Merge requests and ★ Stars are always welcome.
  • For bugs and feature requests, please create an issue.




This project is licensed under the MIT License - see the LICENCE file for details

© 2023 Gatsby, Inc.