Safari Web Extensions localization notes

The common WebExtension format

Apple adopted the WebExtension standard starting with Safari 14 (macOS Big Sur, 2020). This means the i18n file structure is identical to Chrome and Firefox:

my-safari-extension/
├── manifest.json           ← "default_locale": "en" required
└── _locales/
    ├── en/
    │   └── messages.json
    ├── de/
    │   └── messages.json
    ├── ja/
    │   └── messages.json
    └── fr/
        └── messages.json

A messages.json file that works in Chrome works in Safari without modification. The same $PLACEHOLDER$ syntax, the same $1–$9 positional substitutions, and the same __MSG_key__ manifest substitution all work. If you already have a working Chrome or Firefox extension with _locales, the Safari version will use the same files.

browser.i18n in Safari

Safari exposes the i18n API as browser.i18n — the same namespace as Firefox. It also supports chrome.i18n as an alias for Chrome compatibility. The method signatures are identical across all three browsers:

// All three work in Safari:
browser.i18n.getMessage("appName");
browser.i18n.getMessage("welcomeMessage", ["Alice"]);
browser.i18n.getUILanguage();

// Chrome-compat alias also works:
chrome.i18n.getMessage("appName");

If you maintain a single codebase for Chrome, Firefox, and Safari, the cross-browser shim from the Firefox i18n article works for all three:

// i18n.js — cross-browser shim (Chrome + Firefox + Safari)
const i18n = (typeof browser !== "undefined" ? browser : chrome).i18n;

export function t(key, substitutions) {
  return i18n.getMessage(key, substitutions);
}

messages.json format in Safari

Safari supports the full WebExtension message schema — all three fields work exactly as in Chrome and Firefox:

{
  "appName": {
    "message": "My Safari Extension",
    "description": "Name shown in Safari toolbar and App Store listing."
  },
  "tabCount": {
    "message": "$COUNT$ tabs open",
    "description": "Status text showing the number of open tabs.",
    "placeholders": {
      "count": {
        "content": "$1",
        "example": "5"
      }
    }
  },
  "welcomeMessage": {
    "message": "Welcome, $USER_NAME$!",
    "description": "Greeting shown when user opens the extension popup.",
    "placeholders": {
      "user_name": {
        "content": "$1",
        "example": "Alice"
      }
    }
  }
}

Safari extension project structure in Xcode

Unlike Chrome and Firefox where you load an unpacked folder or ZIP, Safari Web Extensions are wrapped in a native macOS/iOS app. Apple provides a conversion tool and Xcode template:

# Convert an existing Chrome/Firefox extension to Safari
xcrun safari-web-extension-converter /path/to/your/extension

# This creates an Xcode project with:
# MyExtension/
# ├── MyExtension.xcodeproj
# ├── Shared (Extension)/
# │   └── Resources/
# │       ├── manifest.json
# │       ├── _locales/
# │       │   ├── en/messages.json
# │       │   ├── de/messages.json
# │       │   └── ...
# │       ├── popup.html
# │       └── background.js
# └── macOS (App)/
# └── iOS (App)/

The important path is Shared (Extension)/Resources/. This is where your _locales/ folder lives inside the Xcode project. When you extract LocalePack’s ZIP output, copy the locale folders into this Resources/ directory and make sure they are included in the Xcode build target.

Manifest V2 vs V3 in Safari

Safari supports both Manifest V2 and Manifest V3. The i18n system is identical in both versions — the _locales folder, messages.json format, default_locale, and __MSG_key__ substitution all work the same way regardless of manifest version.

{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "description": "__MSG_appDescription__",
  "default_locale": "en",
  "version": "1.0.0"
}

Apple’s safari-web-extension-converter tool handles both MV2 and MV3 input. If you’re porting an existing Chrome MV3 extension, the converter will preserve your manifest and _locales folder as-is.

Mac App Store & iOS App Store submission

Safari extensions are distributed through the App Store, not a web-based add-on store. This creates an important distinction in how localization works:

Locale codes in Safari

Safari follows the WebExtension locale code convention — lowercase language code with optional underscore-separated region. The codes used in _locales/ folder names are the same as Chrome:

Testing Safari extension i18n locally

To test your Safari Web Extension in different locales during development:

# Alternatively, run from command line with a specific locale:
# (requires the extension app to be built first in Xcode)
open -a Safari --args -AppleLanguages "(de)"

Common Safari-specific pitfalls

Cross-browser compatibility summary