chrome.i18n: the complete API reference

The whole API at a glance

The entire surface is four methods. Read the middle column first: it is the part that trips people up.

Everything below expands on one row of that table.

Prerequisites, briefly

Three of the four methods work with no setup at all. getMessage() is the exception: it needs message catalogues on disk and a default_locale in the manifest.

my-extension/
├── manifest.json          "default_locale": "en"
└── _locales/
    ├── en/
    │   └── messages.json  ← the default_locale catalogue
    └── de/
        └── messages.json

Those two pieces are a matched set — declare one without the other and Chrome refuses to load the extension. We cover the rules and the exact error strings in default_locale: rules and common errors, and the directory layout in the _locales structure guide. The rest of this page assumes both are in place.

getMessage()

The method you will call thousands of times. It is synchronous and returns a string. There is no promise, no callback, and no loading state — Chrome resolves the catalogue before your code runs.

chrome.i18n.getMessage(messageName, substitutions?)  // → string

// Simple lookup
chrome.i18n.getMessage("appName")
// → "Tab Sorter"

// One substitution
chrome.i18n.getMessage("greeting", ["Ada"])
// → "Hello, Ada!"

// Several substitutions, in order
chrome.i18n.getMessage("summary", ["Ada", "12"])
// → "Ada, you have 12 tabs open."

// A single substitution may be passed as a bare string
chrome.i18n.getMessage("greeting", "Ada")

Because it is synchronous, it composes directly into templates and JSX with no ceremony:

// No await, no useEffect, no loading branch
document.title = chrome.i18n.getMessage("appName")

// React
<h1>{chrome.i18n.getMessage("appName")}</h1>

Substitutions and $1–$9

The second argument fills numbered slots in the message string. The values are positional: $1 is the first array element, $2 the second, up to $9.

The recommended form uses a named placeholders block:

// _locales/en/messages.json
{
  "summary": {
    "message": "$USER$, you have $COUNT$ tabs open.",
    "description": "Shown at the top of the popup",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Ada"
      },
      "count": {
        "content": "$2",
        "example": "12"
      }
    }
  }
}

The named form is worth the extra lines. Translators see $USER$ rather than $1, so they know what the value is, and the example field tells them what it looks like. Crucially, it also lets them reorder the placeholders — many languages will not put the name first — without ever touching the numbered indices, which stay bound to your argument order.

The two documented failure returns

This is the part competitors leave out, and it is the part that costs debugging time. getMessage() does not throw. It fails by returning a value, and the two failure values mean different things.

Telling them apart is the fastest way to narrow a bug. An empty string means look at your catalogues; an undefined means look at your call site. The empty-string case has its own dedicated walkthrough in chrome.i18n.getMessage() returns an empty string.

> chrome.i18n.getMessage("appNmae")     // typo in the key
< ""

> chrome.i18n.getMessage(42)             // not a string
< undefined

getUILanguage() vs getAcceptLanguages()

These two look interchangeable and are not. They answer different questions, have different return types, and one of them is asynchronous.

chrome.i18n.getUILanguage()      // → string          (synchronous)
chrome.i18n.getAcceptLanguages() // → Promise<LanguageCode[]>  (asynchronous)

Because one is a promise, the calling code differs:

// Synchronous — use the value immediately
const ui = chrome.i18n.getUILanguage()
console.log("Extension strings are coming from:", ui)

// Asynchronous — await it
const accepted = await chrome.i18n.getAcceptLanguages()
console.log("User reads:", accepted)   // e.g. ["en-US", "en", "de"]

One practical note on formats: locale identifiers you get back from the browser are not necessarily spelled the way _locales folders are. Chrome folder names use underscores and a fixed accepted list, so do not feed a value straight from these methods into a path without checking it against the supported locale codes.

detectLanguage()

The odd one out. It has nothing to do with your extension’s own localization — it tells you what language a piece of arbitrary text appears to be written in.

chrome.i18n.detectLanguage(text)   // → Promise<object>  (asynchronous)

const result = await chrome.i18n.detectLanguage(
  "Der Text, dessen Sprache erkannt werden soll."
)

It is asynchronous and resolves to an object describing the detected languages. Consult the official chrome.i18n reference for that object’s exact fields before depending on its shape — detection results include confidence information, and treating a low-confidence guess as fact is how this API produces bad user experiences.

For the second column, the answer is always getUILanguage() — or, better, nothing at all, because Chrome already picked the catalogue for you before getMessage() ran.

browser.i18n vs chrome.i18n

Same API, different namespace. Which one exists depends on the browser your code is running in, not on what the API does.

Because Firefox and Safari both accept chrome.i18n while Chrome does not provide browser, the simplest portable choice is to write chrome.i18n everywhere and ship the same code to all three stores.

If you prefer the browser namespace — usually because the rest of your extension uses promise-based WebExtension APIs — load Mozilla’s webextension-polyfill, which provides a browser object in Chrome:

import browser from 'webextension-polyfill'

// Works identically in Chrome, Firefox and Safari
browser.i18n.getMessage("appName")

The catalogue format is identical across all three browsers, so the same _locales tree ships everywhere. Store-level differences are covered in the Firefox and Safari guides.

Unsupported locales fail silently

Chrome accepts a fixed list of locale codes for _locales folder names. What happens to a code outside that list is stated plainly in the documentation:

“If you use an unsupported locale, Google Chrome ignores it.”

Ignores — not rejects. There is no build error, no load error, and no console warning. The folder sits in your extension, contributes nothing, and every user who should have received it falls through to your default_locale instead. From the outside this is indistinguishable from a working extension, which is why it survives code review and ships.

The full accepted list — and which of your folders will quietly do nothing — is in Chrome extension locale codes.

Quick reference

Frequently asked questions