getUILanguage()

What is getUILanguage()?

The browser.i18n.getUILanguage() method is part of the browser extension internationalization (i18n) API that retrieves the language code representing the browser's current user interface language. Unlike methods that return a user's preferred languages, getUILanguage() specifically returns the language that the browser uses for its menus, dialogs, and other interface elements.

This API is particularly valuable because it provides a single, reliable value that represents the language the user is most comfortable with at the system level. Understanding how to properly use this API is essential for building internationally-friendly browser extensions that feel native to users around the world.

When a user installs a browser, they select their preferred display language, and the browser uses this setting throughout its interface. The getUILanguage() method accesses this same setting, allowing extension developers to align their extension's default language with the browser's interface language, creating a cohesive experience where users feel your extension is an integral part of their browser environment. Our web development services team specializes in building cross-browser extensions that deliver seamless internationalization.

Syntax and Parameters

The getUILanguage() method has a remarkably simple interface:

// In Firefox/Chrome extensions using webextension-polyfill
browser.i18n.getUILanguage()

// In Chrome extensions
chrome.i18n.getUILanguage()

Return Value

The method returns a string representing the language code in BCP 47 format:

• "en" - English (generic)
• "en-US" - English (United States)
• "fr" - French
• "de" - German
• "ja" - Japanese
• "zh-CN" - Chinese (Simplified)

Parameters: None - This method takes no parameters and returns a string immediately. This simplicity makes it easy to incorporate into any extension's code. The returned string follows the BCP 47 standard for language tags, which typically consists of a two-letter language code (ISO 639-1) optionally followed by a hyphen and a two-letter country code (ISO 3166-1 alpha-2).

According to the MDN Web Docs on i18n.getUILanguage(), this method provides a reliable way to access the browser's UI language setting for extension localization purposes.

getUILanguage vs getAcceptLanguages

One of the most important distinctions in the browser extension i18n API is between getUILanguage() and getAcceptLanguages():

getUILanguage()

• Returns the browser UI language
• Single value representing the browser's display language
• Set when user installs browser or through language settings
• Use for: Extension interface localization

getAcceptLanguages()

• Returns user's preferred languages for web content
• Array of language codes ordered by preference
• Includes multiple languages user understands
• Use for: Content prioritization, translation features

Use getUILanguage() when you want to display your extension's interface in the same language as the browser, need a single reliable language value for default localization, or want your extension to feel like a native part of the browser. Use getAcceptLanguages() when you need to prioritize content for the user, want to offer content in multiple languages based on preference, or need to sort and filter content by language preference.

As documented in the MDN Extension Internationalization Guide, understanding this distinction is crucial for building properly internationalized extensions.

Language Code Format (BCP 47)

The getUILanguage() method returns language codes that conform to the BCP 47 standard, which is the internet standard for language tags.

Structure

• Primary language subtag: Required, 2-3 letters (ISO 639-1): en, fr, ja, zh
• Script subtag (optional): 4 letters: Hans (Simplified), Hant (Traditional)
• Region subtag (optional): 2 letters: US, GB, CN

Examples

• "en" - English (any region)
• "en-US" - English (United States)
• "zh-Hans-CN" - Chinese (Simplified, China)
• "sr-Cyrl-RS" - Serbian (Cyrillic, Serbia)

Parsing Example

function parseLanguageTag(tag) {
 const parts = tag.split('-');
 return {
 language: parts[0],
 script: parts.length > 2 ? parts[1] : null,
 region: parts.length > 2 ? parts[2] : (parts.length === 2 ? parts[1] : null)
 };
}

Best Practices for Extension Internationalization

1. Use Message Bundles (messages.json)

Never hardcode localized strings. Use the extension's built-in i18n support with messages.json files in your _locales/ directory:

// _locales/en/messages.json
{
 "extensionName": {
 "message": "My Extension",
 "description": "Name of the extension"
 },
 "welcomeMessage": {
 "message": "Welcome to our extension!",
 "description": "Welcome message"
 }
}

2. Implement Fallback Strategies

function getLocalizedMessage(messageName, locale) {
 const availableLocales = ['en', 'fr', 'de', 'es'];
 
 // Try exact locale match
 if (availableLocales.includes(locale)) {
 return chrome.i18n.getMessage(messageName);
 }
 
 // Try language-only (e.g., 'pt-BR' -> 'pt')
 const languageOnly = locale.split('-')[0];
 if (availableLocales.includes(languageOnly)) {
 return chrome.i18n.getMessage(messageName);
 }
 
 // Fall back to English
 return chrome.i18n.getMessage(messageName);
}

3. Handle Right-to-Left Languages

function applyTextDirection(language) {
 const rtlLanguages = ['ar', 'he', 'fa', 'ur'];
 const isRTL = rtlLanguages.includes(language);
 document.documentElement.dir = isRTL ? 'rtl' : 'ltr';
}

As recommended in the MDN Internationalization Guide, always implement proper fallback strategies and consider RTL language requirements for a complete internationalization approach. When building cross-browser compatible extensions, proper internationalization ensures your extension reaches a global audience effectively.

Browser Compatibility

The getUILanguage() method is supported across all major browser extension platforms:

The method has been stable for many years and is considered a core part of the extension i18n API. According to the Chrome Extensions i18n Reference, no polyfills or fallbacks are typically needed for production extensions targeting these browsers.

Chrome i18n API Overview

The chrome.i18n API provides several methods for internationalization:

• getUILanguage() - Browser UI language (covered in this guide)
• getAcceptLanguages() - User's accepted languages for content
• getMessage() - Retrieve localized messages from messages.json
• detectLanguage() - Detect the language of provided text

These methods work together to enable comprehensive internationalization of browser extensions that serve users worldwide. Our AI-powered development services can help automate localization workflows for large-scale extension projects.

Sources

1. MDN Web Docs - i18n.getUILanguage() - Official Mozilla documentation for browser extension internationalization API
2. Chrome for Developers - chrome.i18n API - Google's official Chrome extension i18n API reference
3. MDN Web Docs - Navigator.language - Web API for detecting user's preferred language
4. MDN - Extension Internationalization Guide - Best practices for extension i18n implementation

Related Resources

• Learn about our Web Development Services
• Browser Extension Development
• Internationalization Best Practices