Locales and text direction
Set language and direction on documents and localized subtrees using the runtime's locale metadata.
Translated text and document direction need to agree. Supplying an Arabic catalog changes the messages, but the browser also needs dir="rtl" to lay out the page in the intended reading direction. Use the resolved locale for both the provider and the document attributes.
Set language and direction together #
In a framework's document or shell component, derive the attributes from the locale selected for that request:
import type { ReactNode } from "react";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";
export function LocalizedDocument({ locale, messages, children }: {
locale: string;
messages: Messages;
children: ReactNode;
}) {
const l = createLingo(locale);
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoProvider locale={locale} messages={messages}>
{children}
</LingoProvider>
</body>
</html>
);
}Keep your framework's required head, script, and hydration components around this pattern. For a localized subtree within another-language page, set lang and dir on its containing element using that subtree's useLingo() result instead. A section attribute does not replace the whole document's language.
Apply attributes in the initial HTML where possible. Updating direction only after hydration can first display the page with the wrong layout.
Read the metadata precisely #
| Member | Meaning |
|---|---|
locale: string | The input locale, unchanged. |
direction: "ltr" | "rtl" | Native Intl.Locale.textInfo direction when available, otherwise the runtime's language-based fallback. |
script: string | undefined | Likely script obtained by maximizing the locale with Intl.Locale. |
region: string | undefined | Likely region from the same maximization. |
For example, createLingo("en") can infer Latn and US. That fills likely locale subtags; it does not locate the reader or establish a billing country. Use actual account or location data when the application needs those facts.
If Intl.Locale is unavailable or the tag is invalid, script and region can be undefined and direction uses the fallback language list. Other native formatters can still reject an invalid tag. Resolve the locale against the application's supported set before rendering.
Make layout follow reading direction #
Use logical CSS properties such as margin-inline-start and padding-inline-end for spacing that follows text direction. Check icons individually: a navigation arrow may need to reverse, while an image of a physical object may not. Locale metadata supplies the direction; the component design determines how it should affect the interface.
The provider does not negotiate a language or fetch messages. Locale-router supplies URL and preference policy. The Next Pages wrapper synchronizes direction but leaves document lang to the application; a TanStack shell sets both from request context.
After a language switch, check the document attributes and loaded catalog together. Server rendering explains why the same locale, messages, and formatting inputs must also reach hydration.