Home / lwc / lwc-internationalization

lwc-internationalization

Build LWCs with translation, locale-aware formatting, and RTL layouts. Triggers: LWC i18n, custom labels LWC, RTL layout, @salesforce/label import, @salesforce/i18n locale, timeZone, currency, Intl.NumberFormat in LWC, Translations metadata, date off by one day, mock a label in Jest. NOT for Translation Workbench admin setup — use admin/custom-label-management. NOT for org-wide multi-language config — use admin/multi-language-and-translation.

• v1.2.0
• Salesforce Spring '25+
• Updated 2026-09-05
• User Experience

• i18n
• custom-labels
• locale

Open the skill folder on GitHub

LWC Internationalization

@salesforce/label/c.MyLabel imports a translated string; @salesforce/i18n/* exposes the running user's language, direction, locale, currency and time zone; lightning-formatted-* and Intl.* turn a raw value into something that user can read. This skill covers the component half: which value comes from the user and which from the record, where a base component beats Intl, why a Date field loses a day and a DateTime field does not, and how to test any of it when Jest never sees the org.

Before Starting

Gather this context before writing markup:

• Which languages are actually enabled in the target org, and is any of them right-to-left?
• Which of the values on screen are Date, which are DateTime, and which are Currency?
• Does this component also have to run on an LWR Experience Cloud site?
• Is the org multi-currency, and does the record carry a CurrencyIsoCode?

Questions to Ask Before Configuring

Each question decides a branch that is expensive to reverse, and each traces to a gotcha in references/gotchas.md.

What a proper configuration adds over just doing it: every user-visible string reaches a translator instead of a developer, every formatted value agrees with the reports and list views the same user is looking at, and the three failures that are otherwise invisible — an untranslated label, a date shifted by a day, a translation that will not fit — are caught by the checker and the Jest suite before anyone in the target language sees them.

Adoption Signals

Any LWC used in an org with multiple active locales.

• Required when string concatenation, plural forms, or relative-time formatting hard-codes English in the template.
• Required when the layout must support RTL languages (Arabic, Hebrew) — bidirectional CSS is non-trivial.
• Required when the org is multi-currency and the component renders an amount.
• Required when the same bundle is reused on an LWR Experience Cloud site.

Core Concepts

Two Modules, Two Different Questions

@salesforce/label/* answers "what does this string say in the running user's language". @salesforce/i18n/* answers "what conventions does the running user read numbers, dates and text direction by". They are independent settings on the user record — a user can read English and format numbers German-style — so conflating them produces a component correct for neither.

The Specifier Is Static, the Value Is Not

The module identifier must be a literal in a static import. The value behind it is supplied per user at runtime, which is why one deployed bundle serves every language. That split is the whole design; trying to build a label name from a variable defeats the static half and gets you nothing dynamic in return.

Base Component First, Intl Second, Raw Never

The guide's own recommendation is lightning-formatted-* and lightning-input, which read the platform settings themselves. Intl.DateTimeFormat / Intl.NumberFormat with the imported locale is the documented fallback for what a base component cannot host — a chart axis, an aria-label, a string passed to a third-party library. toLocaleDateString() with no argument is neither: it reads the browser.

The Enumerated i18n Property Set

lang, dir, locale, defaultCalendar, defaultNumberingSystem, calendarData, currency, firstDayOfWeek, isEasternNameStyle, common.calendarData, common.digits, the seven dateTime.* format patterns, the fourteen number.* symbols and patterns, showJapaneseCalendar, and timeZone. All are documented in references/code-examples.md with their sample values, and all are returned for the current user. Anything not on that list does not exist as an @salesforce/i18n identifier.

Decision Guidance

Recommended Workflow

1. Answer the Questions table, then write the string inventory: every user-visible

   string, tagged as a whole sentence or a standalone term, with its longest expected translation. Anything over 765 characters gets split now, not later.

2. Create the labels first. Copy the CustomLabels block from

   references/code-examples.md § 5 — fullName, language, protected, shortDescription, value are all Required — and add a <customLabels> entry to each translations/<locale>.translation-meta.xml (§ 6) in the same commit.

3. Build the bundle from references/code-examples.md §§ 1–4. Start from

   templates/lwc/component-skeleton/; the i18n-specific parts are the literal label imports, the <div lang={lang} dir={dir}> wrapper, the openedOn / lastModifiedText split between timeZone: 'UTC' and the user's zone, and the logical-properties CSS. Check the base-component path before reaching for Intl.

4. Write the Jest suite from § 7, mocking every label with

   jest.mock(..., { virtual: true }) and pinning @salesforce/i18n/locale, dir, currency and timeZone. Copy templates/lwc/jest.config.js and add the i18n mapper from § 8. Harness questions beyond this belong to lwc/lwc-testing.

5. Run the checker:

   python3 skills/lwc/lwc-internationalization/scripts/check_lwc_internationalization.py --manifest-dir force-app/main/default --strict then npx sfdx-lwc-jest. Fill in templates/lwc-internationalization-template.md as you go.

6. Deploy in the order in § 10 — labels, then bundle, then translations — using the

   package.xml in § 9. Note the singular CustomLabel type; the plural one with named members retrieves nothing.

7. Verify as a user in the target language using the six steps in § 11, including the

   Pacific-time-zone check for the Date field and one right-to-left language. Every failure in this domain is silent, so nothing else counts as evidence.

Review Checklist

• [ ] No literal user-facing text node remains in any HTML template.
• [ ] Every @salesforce/label import resolves to a label defined in the repo.
• [ ] Every sentence containing a value is one label with a {0} placeholder.
• [ ] Date fields format with timeZone: 'UTC'; DateTime fields format in the user's zone.
• [ ] Currency binds to the record's CurrencyIsoCode where the org is multi-currency.
• [ ] No toLocaleDateString() / toLocaleString() without an explicit locale.
• [ ] The stylesheet uses logical properties, not left/right or [dir="rtl"].
• [ ] lang and dir are bound onto a wrapper element.
• [ ] Every label has a <customLabels> entry in every active <locale>.translation file.
• [ ] No master label value sits in the 766–1,000 character band.
• [ ] The Jest suite mocks its labels and pins its locale; no assertion on English text.
• [ ] package.xml ships CustomLabel (singular, named members) and Translations.
• [ ] scripts/check_lwc_internationalization.py --manifest-dir <source> --strict is clean.

Common Gotchas (see references/gotchas.md)

• Two ceilings — a label value holds 1,000 characters; its translation holds 765.
• CustomLabels by name retrieves nothing — the plural type takes only *.
• No namespace retrieval — CustomLabels cannot be retrieved with a namespace at all.
• Labels ship without translations — separate type, separate folder, no warning.
• Jest labels are paths — an unmocked label evaluates to c.MyLabel, not its text.
• LWR drops three properties — currency, currencySymbol, currencyFormat.
• Picklist label is translated; value never is — never compare on the label.
• Date-only fields lose a day — the user's time zone shifts an assumed UTC midnight.
• [dir] selectors fail in native shadow DOM — use logical properties or :dir().
• lang and dir are yours to bind — the platform does not stamp them for you.

Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)

• Building a label name at runtime from a variable
• Assembling a sentence out of translated fragments
• Formatting dates and numbers by hand with toLocaleString()
• Reading navigator.language instead of @salesforce/i18n/locale
• Quoting 255 (or 1,000) as the label limit that matters
• Treating right-to-left as a CSS problem to solve later
• Shipping labels and calling the component translated
• Asserting on English text in a Jest test

Output Artifacts

Reference Files

Related Skills

• admin/custom-label-management - owns the declarative side: creating, categorising and governing labels in Setup.
• admin/multi-language-and-translation - owns enabling languages and running the Translation Workbench; this skill assumes both are done.
• lwc/lwc-accessibility - owns lang semantics for screen readers and the rest of the accessibility surface; use alongside this skill's dir handling.
• lwc/lwc-testing - owns the Jest harness, config and wire mocks; this skill covers only the label and locale mocks.
• lwc/lwc-forms-and-validation - use when the translated strings are field labels and validation messages in a form.
• lwc/lwc-data-table - owns column-level formatting and cell types; use it for a table rather than formatting each cell here.
• lwc/lwc-css-and-styling - use for the styling mechanics behind the logical-properties stylesheet.

Package files

• references/code-examples.md
• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/lwc-internationalization-template.md
• scripts/check_lwc_internationalization.py