Usage

Basic Translation

Once your layout is configured, simply use getTranslations(namespace) in any page to get a typed translation function for a specific namespace.

src/pages/[lang]/index.astro

---
import { getTranslations } from "astro-intl";

// No need to call setRequestLocale here - it's already in the layout!
const tHero = getTranslations("hero");
const tNav  = getTranslations("nav");
---

<h1>{tHero("title")}</h1>
<p>{tHero("description")}</p>
<a href="/">{tNav("home")}</a>

Interpolation

Use {curlyOpen}varName{curlyClose} placeholders in your translation strings and pass a values object as the second argument to t(). Accepted types: string, number, boolean. Missing or null/undefined values keep the placeholder unchanged.

en.json — message with variables

{
  "hero": {
    "greeting": "Hello, {name}!",
    "info": "You have {count} new messages"
  }
}

Component.astro — t() with values

---
const tHero = getTranslations("hero");
---

<p>{tHero("greeting", { name: "John" })}</p>
<!-- "Hello, John!" -->

<p>{tHero("info", { count: 5 })}</p>
<!-- "You have 5 new messages" -->

<p>{tHero("greeting")}</p>
<!-- "Hello, {name}!" — placeholder kept when no values -->

Markup Translation

Use t.markup(key, tags) to interpolate HTML tags inside a translation string. The tags object maps tag names to functions that receive the inner content.

en.json — message with tags

{
  "hero": {
    "description": "A <bold>type-safe</bold> solution for <link>Astro</link>"
  }
}

Component.astro — t.markup()

---
const tHero = getTranslations("hero");
---

<p set:html={tHero.markup("description", {
  bold: (chunks) => `<strong>${chunks}</strong>`,
  link: (chunks) => `<a href="https://astro.build">${chunks}</a>`,
})} />

Markup + Interpolation

Combine variable interpolation with tag replacement by passing {curlyOpen} values, tags {curlyClose} to t.markup(). Interpolation runs first, then tags are processed.

en.json — variables + tags

{
  "hero": {
    "welcome": "Hello {name}, read our <link>docs</link> to get started"
  }
}

Component.astro — t.markup() with values

---
const tHero = getTranslations("hero");
---

<p set:html={tHero.markup("welcome", {
  values: { name: "John" },
  tags: {
    link: (chunks) => `<a href="/docs">${chunks}</a>`,
  }
})} />
<!-- "Hello John, read our <a href="/docs">docs</a> to get started" -->

t.raw() — Raw Values

Use t.raw(key) to access the raw translation value without string coercion. Perfect for arrays, objects, and numbers that you need in their native JavaScript type.

Accessing Arrays

When your translations contain arrays, t.raw() returns them as real JavaScript arrays instead of the string [object Object].

messages/en.json

{
  "features": ["Fast", "Lightweight", "Type-safe"]
}

Component.astro

---
import { getTranslations } from "astro-intl";
const t = getTranslations();

// Get raw array
const features = t.raw("features") as string[];
// features = ["Fast", "Lightweight", "Type-safe"]
---

<ul>
  &#123;features.map(feature => &lt;li&gt;&#123;feature&#125;&lt;/li&gt;)&#125;
&lt;/ul&gt;

Accessing Objects

Objects are returned as-is, allowing you to access nested properties directly without parsing.

messages/en.json

{
  "theme": {
    "primary": "#3b82f6",
    "secondary": "#64748b"
  }
}

Component.astro

---
const theme = t.raw("theme") as { primary: string; secondary: string };
// theme = { primary: "#3b82f6", secondary: "#64748b" }
---

&lt;div style={`background: &#36;{theme.primary}`}&gt;...&lt;/div&gt;

Accessing Numbers

Numbers stay as numbers — useful for calculations or passing to components that expect numeric values.

messages/en.json

{
  "config": {
    "maxItems": 100,
    "timeout": 30
  }
}

Component.astro

---
const maxItems = t.raw("config.maxItems") as number;
// maxItems = 100 (number, not string)

// Can use for calculations
const limit = maxItems * 0.8; // 80
---

getTranslationsReact is deprecated since v2.0.0. Use astro-intl/react instead. See React docs

React Components Deprecated

Use getTranslationsReact(namespace) inside React components, then call t.rich(key, tags) to interpolate React nodes.

MyComponent.tsx — t.rich()

import { getTranslationsReact } from "astro-intl";

export default function MyComponent() {
  const t = getTranslationsReact("hero");

  return (
    <p>
      {t.rich("description", {
        bold: (chunks) => <strong>{chunks}</strong>,
        link: (chunks) => <a href="https://astro.build">{chunks}</a>,
      })}
    </p>
  );
}