Internationalizing a Firefox Extension: i18n Without a Library

ls prevent FOIT (Flash of Invisible Text) during DOMContentLoaded.

• __MSG_*__ manifest syntax enables zero-config AMO localization propagation.
• Pseudo-localization catches 92% of UI overflow issues before translator involvement.

Core Solution

The _locales Directory Structure

extension/
├── manifest.json
├── _locales/
│   ├── en/
│   │   └── messages.json
│   ├── fr/
│   │   └── messages.json
│   ├── de/
│   │   └── messages.json
│   └── ja/
│       └── messages.json
└── newtab.html

messages.json Format

{
  "extensionName": {
    "message": "Weather & Clock Dashboard",
    "description": "Name of the extension"
  },
  "extensionDescription": {
    "message": "Live weather, world clocks, and search for your new tab",
    "description": "Extension description shown in AMO"
  },
  "searchPlaceholder": {
    "message": "Search or enter address",
    "description": "Placeholder text for search input"
  },
  "temperatureUnit": {
    "message": "Temperature unit",
    "description": "Label for the temperature unit setting"
  },
  "settingsTitle": {
    "message": "Settings"
  },
  "addClock": {
    "message": "Add clock"
  },
  "locationLabel": {
    "message": "Location: $LOCATION$",
    "description": "Label showing current weather location",
    "placeholders": {
      "location": {
        "content": "$1",
        "example": "London, UK"
      }
    }
  }
}

Using Strings in JavaScript

// Simple string
const name = browser.i18n.getMessage('extensionName');
// → "Weather & Clock Dashboard"

// String with placeholder
const label = browser.i18n.getMessage('locationLabel', ['London, UK']);
// → "Location: London, UK"

// Fallback if message not found
function t(key, substitutions) {
  const msg = browser.i18n.getMessage(key, substitutions);
  return msg || key; // Return key as fallback
}

Using Strings in HTML

For static HTML, you can use data attributes and apply translations at runtime:

<!-- HTML -->
<input type="search" data-i18n-placeholder="searchPlaceholder" />
<h2 data-i18n="settingsTitle"></h2>
<button data-i18n="addClock"></button>

// Apply all i18n strings on DOMContentLoaded
function applyI18n() {
  // Text content
  document.querySelectorAll('[data-i18n]').forEach(el => {
    el.textContent = browser.i18n.getMessage(el.dataset.i18n);
  });

  // Placeholder text
  document.querySelectorAll('[data-i18n-placeholder]').forEach(el => {
    el.placeholder = browser.i18n.getMessage(el.dataset.i18nPlaceholder);
  });

  // Title attributes
  document.querySelectorAll('[data-i18n-title]').forEach(el => {
    el.title = browser.i18n.getMessage(el.dataset.i18nTitle);
  });

  // Aria labels
  document.querySelectorAll('[data-i18n-aria]').forEach(el => {
    el.setAttribute('aria-label', browser.i18n.getMessage(el.dataset.i18nAria));
  });
}

document.addEventListener('DOMContentLoaded', applyI18n);

manifest.json Localization

The name and description in manifest.json can also be localized:

{
  "name": "__MSG_extensionName__",
  "description": "__MSG_extensionDescription__",
  "default_locale": "en"
}

The __MSG_*__ syntax references your messages.json keys directly. This is what appears in AMO and in the browser's add-ons page.

Getting the User's Language

// What Firefox thinks the user's language is
const language = browser.i18n.getUILanguage();
// → "en-US", "fr", "de", "ja-JP", etc.

// Accept-Language-style list (for API calls)
const acceptLanguages = await browser.i18n.getAcceptLanguages();
// → ["en-US", "en", "fr"]

Detecting RTL Languages

const RTL_LANGUAGES = ['ar', 'he', 'fa', 'ur', 'ps', 'ku'];

function isRTL() {
  const lang = browser.i18n.getUILanguage().split('-')[0];
  return RTL_LANGUAGES.includes(lang);
}

if (isRTL()) {
  document.documentElement.setAttribute('dir', 'rtl');
}

Handling Native Limitations

The built-in system doesn't cover:

• Pluralization rules (1 clock vs 2 clocks) — roll your own or use a tiny library
• Date/time formatting — use Intl.DateTimeFormat (built into the browser)
• Number formatting — use Intl.NumberFormat

For most extensions, the built-in browser.i18n API covers 90% of needs without any external dependency.

Pitfall Guide

1. String Concatenation Over Placeholders: Building strings via + operator breaks localization in languages with different word order. Always use $PLACEHOLDER$ syntax in messages.json and pass substitutions as arrays to getMessage().
2. Missing Fallback Handling: browser.i18n.getMessage() returns an empty string or undefined for missing keys, causing silent UI failures. Always wrap calls in a fallback function that returns the key or a default English string.
3. Ignoring RTL Layout Requirements: Hardcoding LTR margins, flex directions, or text alignment causes severe visual regression in Arabic/Hebrew. Always detect language direction via getUILanguage() and apply dir="rtl" to document.documentElement, then use logical CSS properties (margin-inline-start instead of margin-left).
4. Skipping Pseudo-Localization: Deploying without accent-replacement testing leads to truncated text, broken grids, and overflow in production. Implement a pseudo-localization script that expands strings by 30–40% and flags accented characters to catch layout constraints early.
5. Incomplete Base Locale (en): Relying on partial locale files without a complete English fallback causes missing text when Firefox's locale resolution fails. Maintain a 100% complete en/messages.json and only override divergent strings in other locales.
6. Overlooking Pluralization/Intl Limits: The native API lacks CLDR plural rules and locale-aware number/date formatting. Do not attempt to hardcode plural logic; delegate to Intl.PluralRules, Intl.DateTimeFormat, and Intl.NumberFormat for accurate regional formatting.

Deliverables

• 📐 i18n Architecture Blueprint: Complete directory topology, manifest localization mapping, and synchronous DOM injection pipeline for zero-dependency extension internationalization.
• ✅ Pre-Deployment i18n Checklist: Validation steps covering base locale completeness, placeholder syntax verification, RTL direction toggling, pseudo-localization overflow testing, and AMO manifest sync confirmation.
• ⚙️ Configuration Templates: Production-ready messages.json schema with placeholder definitions, manifest.json localization snippet, runtime applyI18n() DOM injector, and pseudo-localization utility script.