Internationalization

[sergiodxa]

Proposal

Add internationalization support to Remix out of the box.

Background

Internationalization is something a lot of apps needs, even if you only support a single language it's great to have it from the beginning too because adding it later it's way harder.

From my experience with remix-i18next, answering #help threads or GH Discussions with other developers, I think built-in support from Remix could help to implement it properly, and more importantly out of the box so Remix devs don't need to reach out to popular and huge libraries.

Example i18next core libray is 56.3kB plus 21kB for react-i18next integration, and while remix-i18next is smaller (6.9kB) and most code lives server-side there's a still a need for the other two.

Use Case

• Loading localized strings
• Translation route meta (title, description, etc.)
• Localized route segments
• Detect user language
• Probably provide a way to render localized messages

API/Examples

Loading localized strings

This is maybe the more important part, one way to do this is to tell devs to return them from the loader

export async function loader({ request }: LoaderArgs) {
  let locale = await getLocaleSomehow(request)
  let messages = await getLocalizedMessages(locale)
  return json({ locale, messages })
}

This works, but you may want to load localized messages with a different cache policy then your route data, so one option could be to export a new function just to do this

export async function messages({ request }: MessagesArgs) {
  let locale = await getLocaleSomehow(request)
  let messages = await getLocalizedMessages(locale)
  return json({ locale, messages })
}

Then Remix can even prefetch this endpoint when using <Link prefetch> so the messages and the data can be prefetched in parallel and cached independently.

Another option is that if Remix supports loading namespaced messages it could be possible to simplify this to a static export

export let messages = ["namespace1", "namespace2"]

Then Remix should need to know how to load messages for those namespaces and for the current user locale.

The current version of remix-i18next does something like this using the handle export and with a hook and other functions in entry.server and entry.client it uses this values to load the namespaces messages.

export let handle = { i18n: ["namespace1", "namespace2"]

The problem remix-i18next has with this approach so far is that when doing a client-side navigation Remix waits for preloaded links, loader's data and code, but not for the localized messages causing a flash of missing translations.

Doing it this is way more simpler for the devs but also complex for Remix since now Remix needs to know:

1. The user locale which can be in a cookie, in the session, in the URL (search or route params), in the Accept-Language header, or even in a DB or API
2. Where are localization messages are stored and how to retrieve them, are they in a specific folder? in the public folder? returned from a loader? in a DB? in an API?

Translation route meta

Meta tags needs to be translated along the UI texts, here's it's tricky to do add this to Remix, the way I do it right now is that I get the t function from i18next inside my loader, then I generate my translated texts and return them, and in the MetaFunction I get that from data

export async function loader({ request }: LoaderArgs) {
  let locale = await remixI18next.getLocale(request)
  let t = await remixI18next.getFixedT(locale)
  return json({
    meta: {
      title: t("title value or key"),
      "og:description": t("og:description value or key")
    }
  })
}

export let meta: MetaFunction = ({ data }) => {
  if (!data) return {}
  return data.meta
}

Ideally, we want to be able to translate messages directly in MetaFunction and only use the loader to get data we need like the title of an article

export async function loader({ params }: LoaderArgs) {
  let article = await getArticle(param.slug)
  return json({ article })
}

export let meta: MetaFunction = ({ data, t }) => {
  if (!data) return {}
  return {
    title: t("Read {{title}}", { title: data.article.title }),
  }
}

This would be ideal, but now Remix needs to pass t.

Localized route segments

This is something I haven't do myself but lots of people asks, usually for SEO, the idea is that if I have routes/about.tsx I want the pathnames /about and /sobre (Spanish) to serve the same route.

Right now, the the usually recommended way to do this is by changing the routes in the routes function in remix.config.js.

Another option is to re-export everything from routes/about.tsx from routes/sobre.tsx and keep doing that per locale, but this will not scale IMO.

One option could be to let developers provide a static list of other pathnames a route may serve

export let paths = ["/about", "/sobre"]

If paths is not define use the file name, otherwise use them.

For this I think providing a different optional file-system convention to use in remix.config.js may be simpler.

Detect user language

There are many ways to detect the user preferred language

1. Use a route param like /:locale/route/path
2. Use a search param like /route/path?locale
3. Use the Accept-Language header
4. Use a cookie
5. Use the session
6. Read from the DB or API on every request

Most SPA do of them client-side, but in Remix you can keep all of this server-side only, set the lang attribute on the <html> tag in the root route then use that to detect the locale client-side.

Doing all of these things is not hard by itself and it's all in remix-i18next but I think Remix could provide a way to detect the locale automatically and pass it to loaders and actions

export async function loader({ locale }: LoaderArgs) {
  ...
}

If the developer needs it client-side it can return it from the loader.

The only tricky part here is how to read from a DB/API, what cookie to use, what session and session key to use, what's the name of the search param and what's the possible name of the route param.

If this could be configured somewhere like in entry.server then the user could use default values or customize it

export let languageDetector: LanguageDetectorFunction = async (request, context) => {
  // here the developer can detect the language using any strategy
  return locale
}

This could also be implemented by users if middlewares (see remix-run/react-router#9564) is implemented first.

Probably provide a way to render localized messages

This would be the most complext one, Remix could provide out of the box i18n support, something like i18next or another i18n library but directly in Remix, tied to other features like loading messages, detect the locale, localize route segments or translate meta

// define namespaces for the UI so Remix can prefetch them
export let messages = ["namespace1", "namespace2"]

export async function loader({ t }: LoaderArgs) {
  let message = t("namespace", "key")
  let namespacedT = t("namespace")
  let message2 = namespacedT("key")
  // ...
}

export async function action({ t }: ActionArgs) {
  let message = t("namespace", "key")let namespacedT = t("namespace")
  let message2 = namespacedT("key")
  // ...
}

export let meta: MetaFunction = ({ t }) => {
  let message = t("namespace", "key")let namespacedT = t("namespace")
  let message2 = namespacedT("key")
  // ...
}

export default function View() {
  let t = useTranslation()
  let namespacedT = useTranslation("namespace")
  let message = t("key")
  let message2 = t("key2")
  // ...
}

Open questions

• How much should Remix provide for i18n? Maybe it's ok for Remix to focus only on localized route segments
• How should users tell Remix how to detect the locale?
• How should users tell Remix from where to load localization messages?

Prior Art

• remix-i18next
• Original discussion in the Remix repo Internationalization support #2877
• Another discussion in the Remix repo Room for improvement with Remix + i18n #3847
• Localized route segments in Next.js https://nextjs.org/docs/advanced-features/i18n-routing

[nilsborg]

Yes pls! How is this not a bigger issue yet??! The world has many languages people..

[nilsborg]

Yes we're planning to share that but need some time to put together an example that's not convoluted with a bunch of client specific code nobody needs 😅
But generally: We're also on the one big catch call route approach which indeed brings it's own challenges. Our approach was to implement a sort of site builder in conjunction with Sanity. Our main remaining issue here is that the GROQ query at the root loader lever is pretty big and takes way too long … 🤞 for caching …

[danieljb]

@esonesson here’s a high-level overview. Apart from the splat (catch-all) route we have a top-level $lng parameter configured: app/routes/$lng/(index|$|…).tsx.

This parameter is used to set the locale in the entry.server.tsx (by reading matches during the handleRequest call, see collapsible below). Also the root loader data is populated with the lng from params and there is some logic to redirect to the / index route when the fallback locale is entered, e.g. /en/ → / for en as fallback locale.

This works with some caveats:

• no handling of i18n cookies/sessions
• ignoring browser locale
• ignoring the ?lng= query parameter
• missing out on some niceties of i18next/remix-i18n, namely the elaborate logic that LanguageDetector.detect brings. There doesn’t seem to be a way to configure a custom LanguageDetector which could potentially enable us to do something like let lng = await i18next.getLocale(request, params); (don’t know if that makes sense).
• subsequently dependent on custom logic/queries to check that params.lng is a valid locale

Another thing that proved difficult was automatic redirects to the user’s locale (which is why we abstained from implementing it in the end).

Relevant code snippets (as we do not have a comprehensive example setup on hand)

// app/entry.server.tsx
export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  // …
  const instance = createInstance();

  const lng = remixContext.matches.find(({ params }) => params.lng)?.params.lng;
  const ns = i18next.getRouteNamespaces(context);
  await instance
    .use(initReactI18next)
    .init({
      // rest of the configuration …
      lng: lng || i18n.fallbackLng,
      ns,
    });
  // …

// app/routes/root.tsx
export async function loader({ params }: LoaderArgs) {
  const fallbackLocale = i18n.fallbackLng;
  const locale = params.lng || fallbackLocale;
  const languages = i18n.supportedLngs;
  
  return json({ locale, languages });
}

export default function Root() {
  const { locale } = useLoaderData<typeof loader>();
  useChangeLanguage(locale);
  let { i18n } = useTranslation();

  return (
    <html lang={locale} dir={i18n.dir()} className="antialiased">
      {/* … */}
    </html>
  );
}

// app/routes/index.tsx
export async function loader({ request }: LoaderArgs) {
  const locale = i18n.fallbackLng;

  const pageData = fetchHomePageData(locale);
  return json(pageData);
}

// app/routes/$lng/index.tsx
export async function loader({ params, request }: LoaderArgs) {
  const locale = params.lng;
  const fallbackLocale = i18n.fallbackLng;
  const url = new URL(request.url);

  if (locale === fallbackLocale) {
    return redirect(`/${url.search}`, { status: 302 });
  }

  const pageData = fetchHomePageData(locale);
  if (!pageData) throw new Response("Not Found", { status: 404 });
  
  return json(pageData);
}

Note: @nilsborg is a colleague of mine.

[sergiodxa]

Correct me if I'm wrong, but remix-i18next doesn't support localized routes, right? E.g., /en/blog, /de/blog

That's correct, you can get the locale from the params object in your routes

• no handling of i18n cookies/sessions
• ignoring browser locale
• ignoring the ?lng= query parameter

If you're using the language on the pathname, you don't want any of that anyway, that's why remix-i18next doesn't do anything with that, when you store the locale in the route params getting the locale can be done with params.lng or however you call the param, there's no need to use a library for that.

[universse]

In this case, language detection can still be useful for 1st time user. For eg, we can redirect them to the /fr/blog when they visit the default path /blog if the detected language is French.

I wonder if there is a way to automate creation of routes with $lng parameter, similar to Next.js. So the developer only need to create the base route file e.g. routes/blog.jsx and localized routes are created automatically. This would work better with the flat route proposal (#4482) also, as we do not have to prefix each route file with $lng. I've been trying to do this with the remix.config routes option but no luck.

[sergiodxa]

There’s a proposal in RR repo to have optional route params, so you can do $lng?.blog.tsx and make lng an optional param, so it matches /fr/blog and /blog

[jacknevitt]

Thanks for putting this together. Looking forward to some solutions soon!

[danygiguere]

For people that don't need a bilingual website, they can use the english language file to store their texts. It just makes the code cleaner. For people in bilingual coutries like me in Canada, it's a must ! If I can't set up i18n in a framework, I just can't use it as a tool because most of my clients need a bilingual website.

Remix has pretty much everything so that we don't have to reinvent the wheel every time we start a new project. The internationalization package is the one thing missing !!!

[cliffordfajardo]

Of all the points @sergiodxa mentioned in this proposal:

1. Loading localized strings
2. Translation route meta (title, description, etc.)
3. Localized route segments
4. Detect user language
5. Probably provide a way to render localized messages

I think 2-4 make a lot of sense to bake into Remix & seem like the more straightforward ones as other frameworks like Next have solutions for 2-4.
1 & 5 (localized messages) feels a bit tricky to get right; I've seen localization of strings done a bit different across companies.
Creating a generic solution that would fit the needs of the community might be a challenge but it would be nice pioneering feature for the JS metaframeworks space.

Resource / brainstorm point
message format Github Repo implements the ICU Message format which is a standard used in other programming languages for i18n & is a project of the Open JS Foundation.

The localization of strings would need to work for common cases like:

• loading a localized file from your filesystem OR
• fetching the data from an external source (CMS, which have become popular nowadays...marketing teams etc)
• ....im probably missing other cases...^

Shopify does i18n at scale currently (see: https://www.shopify.com/) so i hope
the remix team shares this RFC with shopify engineering team(s) so they can contribute to this conversaiton and the community can come up with a good general/flexible solution.
Shopify powered remix stores and the community at large building products/blogs/wikis etc with Remix would benefit 💙💿

[cliffordfajardo]

Fictional imagined conversation 😆

Person 1: so with this new app we're building....is Remix going to help us go global?
Person 2: yeah, it has i18n solutions backed in; we're ready to go worldwide 🌍

[sergiodxa]

I agree that 2, 3 and 4 are probably the options that makes more sense to have built-in in Remix, but if the framework provided 1 and 5 it would make it way better than other options in the frontend space.

Also pure backend frameworks have full i18n solutions, like Rails, Laravel or Django. Maybe it would be useful to check what they provide and attempt to build something similar.

If Remix can make it optional with a package like @remix-run/i18n it would allow teams to choose another tool (like my own remix-i18next) or use the standard one which is probably what most would do.

[federicogfernandez]

I will contribute with my experience using remix-i18next.

We started the project with remix-i18next integrated because we needed to ship fast with translations without thinking much about what library to use. After some months developing our application we started to focus on Core Web Vitals and performance in general.

We found out that i18next has several CPU issues causing our app to be CPU intensive in the SSR and also executing some long-tasks in the browser.
Besides the CPU issues it also causes a full re-render when the useChangeLanguage hook calls i18n.changeLanguage function.

So we decided to migrate it and analyzing all the options available we opted for react-intl. We liked that it uses the native Intl API and use polyfills when not supported. After this migration both problems CPU and re-render have gone.

I cannot share the implementation because it's in a private repository but if you want i can make an example app showing it.

[federicogfernandez]

Sorry if i wasn't clear, i'm not talking about actually changing the locale (which obviously should re-render) i mean the first render calling that method inside a hook triggers the re-render.

[sergiodxa]

Ohh I understand now, I haven't realized that would cause a re-render, that's an issue on my side with remix-i18next then, not a i18next issue.

[juniorforlife]

@sergiodxa have you been able to fix the performance issue above?

[juniorforlife]

@federicogfernandez can you please provide an example of how you implement it with react-intl 🙏

[RiddMa]

Ohh I understand now, I haven't realized that would cause a re-render, that's an issue on my side with remix-i18next then, not a i18next issue.

@sergiodxa I'm wondering, has this issue been resolved? I'm starting a new project and evaluating which i18n library to use. Thank you.

[Maxximus007]

Hi, using Remix-i18next myself (thank you for that Sergio!), but found https://github.com/nanostores/i18n and that seems be a reasonable option? Probably overlooking a gazillion other possible issues, but it could be worth to consider as well?

[CanRau]

There's also https://github.com/ivanhofer/typesafe-i18n which might serve as inspiration

[shripadk]

I have been experimenting on this front and feel having a Provider (and even React components) for this is probably overkill (please let me know if I am wrong). Since Remix nicely ties server-side with client code (through loaders), we can just load the locales only on the server, use a library like intl-messageformat only on the server side and send localized strings back to the client. There is no need to send locales to the client saving a lot on bandwidth.

Some code that I tried myself:

1. Assume this is an example locale for en-US and stored in app/locales/en-US/translations.json:

{
  "message":  "Hello, today is {ts, date, ::yyyyMMdd}"
}

2. Setup a formatMessage.server.ts utility function:

import { IntlMessageFormat } from "intl-messageformat"
import invariant from "tiny-invariant"

// loads all locales server-side
import messages from "~/locales"
import { get_closest_match } from "~/utils"

export function formatMessage(
  locale: string,
  key: string,
  variables: Record<string, string>
) {
  const closestLocale = get_closest_match(locale, Object.keys(messages))
  invariant(messages[closestLocale], `Locale ${closestLocale} not found`)
  invariant(messages[closestLocale][key], `Message ${key} in ${closestLocale} not found`)

  const message = messages[closestLocale][key]

  return new IntlMessageFormat(message, closestLocale).format(variables)
}

Your route:

import { useLoaderData } from "@remix-run/react"
import { formatMessage } from "~/utils/formatMessage.server"

export const loader = async () => {
  // the locale can be fetched either from browser request or from stored entry for user in a database
  return formatMessage("en-US", "message", { ts: Date.now().toString() })
}

export default function Index() {
  const message = useLoaderData<typeof loader>()

  // outputs: Hello, today is 08/02/2023
  return <div>{message}</div>
}

[samuelstroschein]

We are exploring building a framework-agnostic i18n library with deep integration for Remix.

We would bundle the efforts of making i18n simple for the web, providing every framework with best-in-class i18n support instead of every framework building its own solution for months. See some of the apps we already provide for localization in the repo https://github.com/inlang/inlang.

Is there interest from the Remix community to support our efforts?

[samuelstroschein]

We started a discussion https://github.com/inlang/inlang/discussions/395

[samuelstroschein]

The library is in pre-release and can be (manually) adapted to remix https://inlang.com/m/gerre34r/library-inlang-paraglideJs

[sergiocarneiro]

Looks like a promising project ✨

[juniorforlife]

@ryanflorence it would be great if someone from Remix core team can collaborate with this project so we can have a more streamlined i18n lib for Remix

[leotuna]

Updates?

[MartinMateju]

found it: https://github.com/BRIKEV/remix-paraglidejs/tree/main

[samuelstroschein]

@MartinMateju you probably want to go with Paraglide JS 2.0 right away opral/inlang-paraglide-js#201 (comment) . React router v7 example is on my list opral/inlang-paraglide-js#376

[juniorforlife]

I got 404 when visited the Paraglide-Remix page

https://inlang.com/m/fnhuwzrx/paraglide-remix-i18n

[MartinMateju]

@samuelstroschein, I really like the tool, but is there any option to access the translations via m-function-matcher dynamically? e.g. m("title")

[samuelstroschein]

Yes there is. You can dynamicallty reference messages via m['title']() but be aware that tree-shaking might be impacted.

The workaround is do define the expected messages in an object ahead of time.

// your bundler will only include those two messages
const messages = {
  title: m.title,
  other: m.happy_elephant
}

let selectedMessage = "other"

messages[selectedMessage]

[mschipperheyn]

Have you guys looked at linguijs? I really liked to automated extraction tools

[juniorforlife]

@mschipperheyn how did you integrate it into Remix? There's no Remix setup tutorial in their docs

[convcha]

@juniorforlife
https://github.com/lingui/js-lingui/tree/main/examples/remix-vite-babel
Remix + Lingui is really cool.
I use it in my products.

[juniorforlife]

@convcha thanks. is it typesafe?

[convcha]

@juniorforlife
In the case of Lingui, the approach is the opposite.

https://lingui.dev/tutorials/react
Rather than using the messages defined in the language definition from the React component, the messages written in the React component are copied to the language definition file.

I don't know if there is a way to use the messages written in the language definition file in a type-safe way from other React components.