Lokalized: make your applications sound natural in any language.

JavaScript

npm install lokalized@1.0.0

<script type="module">
  import { createStrings } from "https://cdn.jsdelivr.net/npm/lokalized@1.0.0/dist/browser/lokalized.js";
</script>

Java

<dependency>
  <groupId>com.lokalized</groupId>
  <artifactId>lokalized</artifactId>
  <version>3.1.2</version>
</dependency>

dependencies {
  implementation("com.lokalized:lokalized:3.1.2")
}

android {
  defaultConfig { minSdk = 26 }
}
dependencies {
  implementation("com.lokalized:lokalized:3.1.2")
}

Swift

Xcode: iOS and macOS apps

In Xcode, choose File → Add Package Dependencies, enter https://github.com/lokalized/lokalized-swift, select Up to Next Major Version starting at 1.0.0, and add the Lokalized product to your app target.

Swift Package Manager

Use Swift 6.2 or later, with iOS 15 and macOS 12 deployment targets or later. The library has zero external runtime dependencies. This package example copies a folder of locale-named JSON files into the resource-owning target. Choose the app, package, or tool setup below:

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
  name: "MyApp",
  platforms: [.iOS(.v15), .macOS(.v12)],
  dependencies: [
    .package(url: "https://github.com/lokalized/lokalized-swift", from: "1.0.0")
  ],
  targets: [
    .executableTarget(name: "MyApp", dependencies: [
      .product(name: "Lokalized", package: "lokalized-swift")
    ], resources: [.copy("Lokalized")])
  ],
  swiftLanguageModes: [.v6]
)

JavaScript

The JavaScript package always uses this snapshot. When your application parses a header itself, use parseLanguageRanges(...) from lokalized/negotiate, which has the same grammar, result order, and errors as the Java library.

Java

The JDK's LanguageRange.parse(...) uses the table bundled in the running JDK instead, which differs between JDK releases. When your application parses a header itself, use strings.parseLanguageRanges(...), which has the same grammar, result order, and exceptions.

To keep Lokalized 3.0.0's behavior of using the running JDK's table, configure languageRangeEquivalents(...) with LanguageRangeEquivalents.JDK. The setting governs parseLanguageRanges(...), bestMatchForAcceptLanguage(...), and the equivalents matching recognizes for each requested range; the default is LanguageRangeEquivalents.IANA_REGISTRY.

Swift

The Swift port uses the bundled IANA registry snapshot. Use strings.parseLanguageRanges(...) for strict parsing, or TranslationOptions.forAcceptLanguage(_:using:) for bounded input with fallback for unusable headers. The strict parsed-list APIs accept at most 32 ranges, including generated IANA equivalents.

JavaScript

Node.js can read localized strings files from a directory; the browser can fetch published files through a manifest. The directory loader scans only the directory it is given and does not recurse into children.

Java

Use the filesystem during development and a namespaced classpath package in packaged applications. Both loaders scan only the requested directory or package; they do not recurse into children.

Swift

Load immediate files from a local directory for macOS tools, or a named resource folder in an iOS/macOS app bundle. Both paths load the same locale-named JSON format. SwiftPM targets that own copied resources pass .module.

JavaScript

import { readStringsFromDirectory } from "lokalized/node";

// In Node: read every localized strings file in one directory
const { catalogs, warnings } = readStringsFromDirectory("strings");

import { writeFileSync } from "node:fs";
import { createStringsManifestFromDirectory } from "lokalized/node";

// At publish time, in Node: record each file's URL and the digest of its bytes
const publishedManifest = await createStringsManifestFromDirectory("strings", {
  catalogVersion: "2026-09-27",
  fallbackLocale: "en",
  publicationBaseUrl: "https://cdn.example.com/strings/",
});
writeFileSync("strings/manifest.json", JSON.stringify(publishedManifest));
// Publish strings/manifest.json with strings/en.json and strings/fr.json

import { createStrings, chooseBrowserLocale } from "lokalized";
import { loadStrings, localeConfigurationForManifest, parseStringsManifest } from "lokalized/load";

// In a browser or edge worker: fetch the manifest from your trusted origin
const response = await fetch("https://cdn.example.com/strings/manifest.json");
if (!response.ok) throw new Error("Could not load the strings manifest");
const manifest = parseStringsManifest(await response.text());
const locale = chooseBrowserLocale(localeConfigurationForManifest(manifest));

// Fetch only the files this locale needs, each checked against its digest
const loaded = await loadStrings(manifest, locale);
const strings = createStrings({ loaded, localeSupplier: () => locale });

strings.get("Hello");   // => "Bonjour"

Java

// Load editable localized strings from a filesystem directory
Strings filesystemStrings = Strings.withFallbackLocale(Locale.ENGLISH)
  .localizedStringSupplier(() -> LocalizedStringLoader
    .loadFromFilesystem(Paths.get("strings")))
  .localeSupplier(matcher -> matcher.bestMatchFor(Locale.US))
  .build();

// Load packaged localized strings from a classpath package
Strings classpathStrings = Strings.withFallbackLocale(Locale.ENGLISH)
  .localizedStringSupplier(() -> LocalizedStringLoader
    .loadFromClasspath("com/example/myapp/strings"))
  .localeSupplier(matcher -> matcher.bestMatchFor(Locale.US))
  .build();

Swift

import Foundation
import Lokalized

// macOS tools: load the immediate files in a local directory.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }

// iOS/macOS apps: use .main; SwiftPM resource owners: use .module.
// Pass an explicit Bundle for a framework's resources.
let bundledFiles = try LocalizedStringLoader.loadFromBundle(.module)

JavaScript

• The manifest is generated once, at publish time, and lists every file, the URL it is published at, and the SHA-256 digest of its bytes. A file whose bytes do not match is refused.
• The manifest is what the digests are checked against, so serve it from an origin you control.
• A load reads the requested locale's fallback chain and nothing else, and hands back a record that createStrings takes as loaded.
• Browser network loading needs WebCrypto: use HTTPS or localhost. If the files are on another origin, that origin must allow cross-origin requests. An edge worker can use the same loader with a locale selected from its request instead of chooseBrowserLocale(...).
• The und.json file is the localized strings filename for the root locale.
• Files use strict UTF-8. Blank or BOM-only files are invalid; use {} for an intentionally empty file.

Java

• Use slash-separated classpath names such as com/example/myapp/strings.
• Use an explicit ClassLoader overload in containers, plugin systems, and test harnesses.
• Leave exhaustiveClasspathSearch disabled unless a JAR omits package directory entries; enabling it scans every visible filesystem and JAR classpath root.
• The META-INF/versions directory is reserved from package discovery; use loadFromClasspathResources(...) when an application intentionally needs an exact resource beneath it.
• The und.json file is the localized strings filename for Locale.ROOT.
• Input streams use strict UTF-8. Blank or BOM-only files are invalid; use {} for an intentionally empty file.
• Classpath discovery skips unrelated .json resources with invalid locale filenames and warns; filesystem loading remains strict.

Swift

• Preserve a Lokalized folder containing en.json, fr.json, and other locale-named files. SwiftPM uses .copy("Lokalized"); Xcode apps preserve the folder in Copy Bundle Resources.
• Pass Bundle.main for an app, Bundle.module from the SwiftPM target that owns resources, or an explicit framework bundle.
• Use resourcePathsByLocale with loadFromBundle, or loadFromResources with local file URLs, for explicit resource mapping.
• Parse caller-owned String, Data, or InputStream values when your application supplies localized strings contents. Lokalized does not download them.

JavaScript

import { readStringsFromDirectory } from "lokalized/node";

// Tighten the resource limits enforced while parsing localized strings
const { catalogs } = readStringsFromDirectory("strings", {
  limits: {
    maximumInputBytes: 4 * 1024 * 1024,
    maximumReaderCharacters: 4 * 1024 * 1024,
    maximumTotalInputBytes: 16 * 1024 * 1024,
    maximumLocalizedStringsFiles: 100,
    maximumTranslationNodes: 25_000,
    maximumWarnings: 500,
    maximumJsonNestingDepth: 32,
  },
});

Java

// Customize the resource limits enforced while parsing localized strings
LocalizedStringLoadingOptions limits = LocalizedStringLoadingOptions.builder()
  .maximumInputBytes(4 * 1024 * 1024)
  .maximumReaderCharacters(4 * 1024 * 1024)
  .maximumTotalInputBytes(16L * 1024L * 1024L)
  .maximumLocalizedStringsFiles(100)
  .maximumTranslationNodes(25_000)
  .maximumWarnings(500)
  .maximumJsonNestingDepth(32)
  .build();

Map<Locale, Set<LocalizedString>> localizedStringsByLocale =
  LocalizedStringLoader.loadFromClasspath("strings", limits);

Swift

import Foundation
import Lokalized

let limits = try LocalizedStringLoadingOptions(
  maximumInputBytes: 4 * 1024 * 1024,
  maximumReaderCharacters: 4 * 1024 * 1024,
  maximumJsonNestingDepth: 32,
  maximumTotalInputBytes: 16 * 1024 * 1024,
  maximumLocalizedStringsFiles: 100,
  maximumTranslationNodes: 25_000,
  maximumWarnings: 500
)
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings"), loadingOptions: limits)

JavaScript

A resolver that reads the current request is convenient for web applications. Async work, tests, batch jobs, and administrative tools can override one call with a TranslationOptions object, the third argument to get:

Java

Request-scoped locale suppliers are convenient for web applications. Async work, tests, batch jobs, and administrative tools can override one call with TranslationOptions:

Swift

Pass an app-owned language setting for each lookup with TranslationOptions.forLocale(...). The same immutable instance can serve different users or windows. Read actor-isolated state on its actor and pass the resulting value into the lookup:

JavaScript

// A per-call locale overrides the instance's resolver for this one lookup
const message = strings.get("I read {{bookCount}} books.", { bookCount: 1 }, { locale: "fr-CA" });

message;   // => "J'ai lu 1 livre."

Java

// With a matching fr-CA translation, this might return "J'ai lu 1 livre."
String message = strings.get(
  "I read {{bookCount}} books.",
  Map.of("bookCount", 1),
  TranslationOptions.forLocale(Locale.forLanguageTag("fr-CA"))
);

Swift

import Foundation
import Lokalized

let locale = try LocaleTag("en")
// Run this during startup, then retain and share strings throughout the app or tool.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs },
  localeSupplier: { _ in locale },
  fallbackLocale: locale
))

let french = try TranslationOptions.forLocale("fr-CA")
let message = try strings.get("I read {{bookCount}} books.",
  placeholders: ["bookCount": .integer(1)], options: french)
assert(message == "J'ai lu 1 livre.")

JavaScript

Per-call options can provide a locale or a localeMatchResult, bidi isolation behavior, a fallback policy, a failure handler, or a fallback observer. Using bidiIsolation: "always" protects caller-supplied right-to-left text inside left-to-right translations as well as the inverse case; "rtl-locales" remains the default. The same matching and tiebreaker rules still apply.

Java

Per-call options can provide a locale or language ranges, bidi isolation behavior, a fallback policy, a failure handler, or a fallback observer. Using BidiIsolation.ALWAYS protects caller-supplied right-to-left text inside left-to-right translations as well as the inverse case; RTL_LOCALES remains the default. The same matching and tiebreaker rules still apply.

Swift

Per-call options can provide a locale, language ranges, or an existing locale match; these three inputs are mutually exclusive. They can also override bidi isolation, fallback policy, failure handler, and fallback observer. Use .always for bidirectional text in either direction; .rtlLocales is the default and .disabled disables isolation.

JavaScript

import { GENDER_COMMON, GENDER_FEMININE } from "lokalized";

const key = "{{heOrShe}} was one of the {{groupSize}} best baseball players.";

strings.get(key, { heOrShe: GENDER_FEMININE, groupSize: 3 });   // => "Fue una de las 3 mejores jugadoras de béisbol."
strings.get(key, { heOrShe: GENDER_COMMON, groupSize: 1 });     // => "Esta persona era quien mejor jugaba al béisbol."

Java

String message = strings.get(
  "{{heOrShe}} was one of the {{groupSize}} best baseball players.",
  Map.of("heOrShe", Gender.FEMININE, "groupSize", 3)
);

assertEquals("Fue una de las 3 mejores jugadoras de béisbol.", message);

message = strings.get(
  "{{heOrShe}} was one of the {{groupSize}} best baseball players.",
  Map.of("heOrShe", Gender.COMMON, "groupSize", 1)
);

assertEquals("Esta persona era quien mejor jugaba al béisbol.", message);

Swift

import Foundation
import Lokalized

let locale = try LocaleTag("es")
// Run this during startup, then retain and share strings throughout the app or tool.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs },
  localeSupplier: { _ in locale },
  fallbackLocale: locale
))

let key: ExactString = "{{heOrShe}} was one of the {{groupSize}} best baseball players."
let matches8 = try strings.get(key, placeholders: [
  "heOrShe": .languageForm(.gender(.feminine)), "groupSize": .integer(3)
]) == "Fue una de las 3 mejores jugadoras de béisbol."
assert(matches8)
let matches9 = try strings.get(key, placeholders: [
  "heOrShe": .languageForm(.gender(.common)), "groupSize": .integer(1)
]) == "Esta persona era quien mejor jugaba al béisbol."
assert(matches9)

JavaScript

Applications normally pass raw values to strings.get(...), but the same CLDR-backed rules are available directly. Visible decimals are significant only when the input preserves them: a JavaScript number cannot hold 1.0 apart from 1, so pass decimal("1.0") or explicit pluralOperands(...) to keep the displayed scale. Ordinal and range helpers live with their optional data, in lokalized/data/ordinal and lokalized/data/ranges.

Java

Applications normally pass raw values to Strings, but the same CLDR-backed rules are available directly. Visible decimals are significant only when the input preserves them: an ordinary double value of 1.0 is normalized like 1, while BigDecimal("1.0") or explicit PluralOperands retains the displayed scale.

Swift

Pass raw NumericValue values or PluralOperands for CLDR selection. A floating-point value does not retain visible trailing zeros; NumericValue.forDecimal("1.0") does. All cardinal, ordinal, and range data is included in the Lokalized product.

JavaScript

import {
  PHONETIC_OTHER, PHONETIC_STRESSED_A,
  cardinalityForNumber, cardinalityForOperands, createStrings, decimal, pluralOperands,
} from "lokalized";
import { ordinalityForNumber } from "lokalized/data/ordinal";
import { readStringsFromDirectory } from "lokalized/node";

cardinalityForNumber(1, "en").name;   // => "CARDINALITY_ONE"

// A JavaScript number cannot carry "1.0"; decimal() keeps the visible decimal
cardinalityForNumber(decimal("1.0"), "en").name;   // => "CARDINALITY_OTHER"

// The same display intent can be supplied explicitly with pluralOperands()
const operands = pluralOperands("1", { visibleDecimalPlaces: 1 });
cardinalityForOperands(operands, "en").name;   // => "CARDINALITY_OTHER"

ordinalityForNumber(21, "en").name;   // => "ORDINALITY_ONE"

const spanishResolver = (term, locale) => {
  if (locale.split("-")[0] !== "es")
    return PHONETIC_OTHER;

  return ["acta", "arma", "hacha"].includes(term.toLowerCase())
    ? PHONETIC_STRESSED_A
    : PHONETIC_OTHER;
};

const strings = createStrings({
  localizedStringSupplier: () => (readStringsFromDirectory("strings").catalogs),
  fallbackLocale: "es",
  localeSupplier: () => "es",
  phoneticResolver: spanishResolver,
});

Java

Locale english = Locale.forLanguageTag("en");

Cardinality cardinality = Cardinality.forNumber(1, english);
assertEquals(Cardinality.ONE, cardinality);

// BigDecimal preserves the visible decimal in "1.0"
cardinality = Cardinality.forNumber(new BigDecimal("1.0"), english);
assertEquals(Cardinality.OTHER, cardinality);

// The same display intent can be supplied explicitly with PluralOperands
PluralOperands operands = PluralOperands.forNumber(1)
  .visibleDecimalPlaces(1)
  .build();
cardinality = Cardinality.forOperands(operands, english);
assertEquals(Cardinality.OTHER, cardinality);

Ordinality ordinality = Ordinality.forNumber(21, english);
assertEquals(Ordinality.ONE, ordinality);

Locale spanish = Locale.forLanguageTag("es");
PhoneticResolver spanishResolver = (term, locale) -> {
  if (!"es".equals(locale.getLanguage()))
    return Phonetic.OTHER;

  String normalized = term.toLowerCase(Locale.ROOT);
  return Set.of("acta", "arma", "hacha").contains(normalized)
    ? Phonetic.STRESSED_A
    : Phonetic.OTHER;
};

Strings strings = Strings.withFallbackLocale(spanish)
  .localizedStringSupplier(() -> LocalizedStringLoader.loadFromClasspath("strings"))
  .phoneticResolver(spanishResolver)
  .localeSupplier(matcher -> spanish)
  .build();

Swift

import Foundation
import Lokalized

let matches14 = try Cardinality.forNumber(.integer(1), locale: "en") == .one
assert(matches14)
// A Double cannot preserve visible decimal places; NumericValue can.
let decimal = try NumericValue.forDecimal("1.0")
let matches15 = try Cardinality.forNumber(decimal, locale: "en") == .other
assert(matches15)
let matches16 = try Ordinality.forNumber(.integer(21), locale: "en") == .one
assert(matches16)

let spanishResolver: PhoneticResolver = { term, locale in
  guard locale.tag == "es" else { return .other }
  return ["acta", "arma", "hacha"].contains(term.lowercased()) ? .stressedA : .other
}
let es = try LocaleTag("es")
let files = try LocalizedStringLoader.loadFromDirectory(URL(fileURLWithPath: "strings"))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs }, localeSupplier: { _ in es },
  fallbackLocale: es, phoneticResolver: spanishResolver
))
let matches17 = try spanishResolver("Arma", es) == .stressedA
assert(matches17)

JavaScript

Locale fallback and final failure handling are separate decisions. The translationFallbackPolicy option decides whether to try another locale; only after fallback stops does the translationFailureHandler function decide what to return or throw.

Java

Locale fallback and final failure handling are separate decisions. A TranslationFallbackPolicy decides whether to try another locale; only after fallback stops does a TranslationFailureHandler decide what to return or throw.

Swift

TranslationFallbackPolicy decides whether a failed candidate advances to another locale. The final TranslationFailureHandler runs only after translation attempts finish. The default policy tries the next candidate for missing translations and unmatched alternatives, but stops for resolution failures. The default handler returns the key; .throwException() throws for a missing translation or rethrows the retained resolution cause. Callback errors propagate directly.

Use .neverFallback() or .fallbackOnAnyFailure() when the application needs a different policy. These choices remain separate from locale negotiation.

JavaScript

import { createStrings } from "lokalized";
import { RETURN_KEY } from "lokalized/core";
import { readStringsFromDirectory } from "lokalized/node";

const strings = createStrings({
  localizedStringSupplier: () => (readStringsFromDirectory("strings").catalogs),
  fallbackLocale: "en",
  localeSupplier: () => "en-US",
  translationFailureHandler: (failure) => {
    exampleMetrics.increment(`lokalized.translation.${failure.reason}`);
    return RETURN_KEY;
  },
});

Java

Strings strings = Strings.withFallbackLocale(Locale.ENGLISH)
  .localizedStringSupplier(() -> LocalizedStringLoader
    .loadFromClasspath("strings"))
  .localeSupplier(matcher -> matcher.bestMatchFor(Locale.US))
  .translationFailureHandler(TranslationFailureHandler.returnKey(failure ->
    exampleMetrics.increment("lokalized.translation." + failure.getReason())))
  .build();

Swift

import Foundation
import Lokalized

let locale = try LocaleTag("en")
// Run this during startup, then retain and share strings throughout the app or tool.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs },
  localeSupplier: { _ in locale },
  fallbackLocale: locale,
  translationFailureHandler: .returnKey(observer: { failure in
    // Send safe diagnostic metadata to the application's thread-safe telemetry.
    print(failure.reason.rawValue, failure.lookupLocale.tag)
  })
))

let matches18 = try strings.get("A missing key") == "A missing key"
assert(matches18)

JavaScript

Failure reasons distinguish "missing-translation", "no-matching-alternative", and "resolution-failure". A failure's message contains only the key, lookup locale, reason, and attempted locales; it omits caller placeholder values and runtime-cause messages. The failure also carries placeholders and cause as separate fields.

Java

Failure reasons distinguish MISSING_TRANSLATION, NO_MATCHING_ALTERNATIVE, and RESOLUTION_FAILURE. The TranslationFailure.getMessage() method contains only the key, lookup locale, reason, and attempted locales; it omits caller placeholder values and runtime-cause messages. The cause remains available separately through getCause().

Swift

Failure reasons are .missingTranslation, .noMatchingAlternative, and .resolutionFailure. TranslationFailure.message includes the key, lookup locale, reason, and attempted locales while omitting placeholder values and cause messages. Placeholder values and the retained cause remain separately available.

JavaScript

Most callers use get(...). Applications that need telemetry, audit trails, or negotiation details can request a structured result with getResult(...):

Java

Most callers use get(...). Applications that need telemetry, audit trails, or negotiation details can request a structured TranslationResult:

Swift

Most callers use try strings.get(...). Use getResult(...) for a structured TranslationResult with translation and negotiation diagnostics:

JavaScript

import { createLocaleMatcher, forLanguageRanges, parseLanguageRanges } from "lokalized/negotiate";

const negotiator = createLocaleMatcher(strings.getLocaleConfiguration());
const translationResult = strings.getResult(
  "I read {{bookCount}} books.",
  { bookCount: 3 },
  forLanguageRanges(negotiator, parseLanguageRanges("pt-PT,pt;q=0.8"))
);

translationResult.translation;             // => "Li 3 livros."
translationResult.lookupLocale;            // => "pt-PT"
translationResult.resolvedLocale;          // => "pt-PT"
translationResult.attemptedLocales;        // => ["pt-PT"]
translationResult.isFallback;              // => false
translationResult.localeMatchResult.matchType;   // => "exact"

Java

TranslationResult translationResult = strings.getResult(
  "I read {{bookCount}} books.",
  Map.of("bookCount", 3),
  TranslationOptions.forLanguageRanges(
    strings.parseLanguageRanges("pt-PT,pt;q=0.8"))
);

// Returned text, e.g. "Li 3 livros."
String message = translationResult.getTranslation();

// Negotiated locale used to begin lookup, e.g. pt-PT
Locale lookupLocale = translationResult.getLookupLocale();

// Locale that supplied the translation, e.g. Optional[pt-PT]
Optional<Locale> resolvedLocale = translationResult.getResolvedLocale();

// Ordered locales actually tried, e.g. [pt-PT]
List<Locale> attemptedLocales = translationResult.getAttemptedLocales();

// Whether negotiation or per-key resolution fell back, e.g. false
Boolean usedFallback = translationResult.isFallback();

// Negotiation details when available, e.g. an exact pt-PT match
Optional<LocaleMatchResult> localeMatchResult = translationResult.getLocaleMatchResult();

Swift

import Foundation
import Lokalized

let locale = try LocaleTag("pt-PT")
// Run this during startup, then retain and share strings throughout the app or tool.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs },
  localeSupplier: { _ in locale },
  fallbackLocale: locale
))

let ranges = try strings.parseLanguageRanges("pt-PT,pt;q=0.8")
let result = try strings.getResult("I read {{bookCount}} books.",
  placeholders: ["bookCount": .integer(3)], options: .forLanguageRanges(ranges))
assert(result.translation == "Li 3 livros.")
assert(result.lookupLocale.tag == "pt-PT")
assert(result.resolvedLocale?.tag == "pt-PT")
assert(result.attemptedLocales.map(\.tag) == ["pt-PT"])
assert(!result.isFallback)
assert(result.localeMatchResult?.matchType == .exact)

JavaScript

Results expose status, resolved locale, attempted locales, whether fallback occurred, the locale match, and any failure reason. Use a localeMatchSupplier, or pass localeMatchResult per call, when the original language ranges and match type must survive into diagnostics.

Java

Results expose status, resolved locale, attempted locales, whether fallback occurred, the locale-match result, and any failure reason. Use localeMatchSupplier(...) when the original language ranges and match type must survive into diagnostics.

Swift

Results expose status, resolved locale, attempted locales, fallback status, the locale-match result, and any failure reason. Supply a localeMatchSupplier or TranslationOptions.forLocaleMatch(...) to retain a match already produced by the same locale configuration.

JavaScript

A Strings instance exposes read-only helpers for audits, coverage tools, and build checks:

Java

A Strings instance exposes read-only helpers for audits, coverage tools, and build checks:

Swift

A Strings instance exposes read-only helpers for audits, coverage tools, and build checks:

JavaScript

strings.getSupportedLocales();        // => ["en", "fr"]
strings.getKeysForLocale("en");       // => ["Goodbye", "Hello"]
strings.getMissingKeys("en", "fr");   // => ["Goodbye"]

Java

// Find the locales currently available for lookup
Set<Locale> supportedLocales = strings.getSupportedLocales();

// List every translation key in the English localized strings file
Set<String> englishKeys =
  strings.getKeysForLocale(Locale.forLanguageTag("en"));

// Find English keys that still need a French translation
Set<String> missingFrenchKeys = strings.getMissingKeys(
  Locale.forLanguageTag("en"),
  Locale.forLanguageTag("fr")
);

Swift

import Foundation
import Lokalized

let locale = try LocaleTag("en")
// Run this during startup, then retain and share strings throughout the app or tool.
let files = try LocalizedStringLoader.loadFromDirectory(
  URL(fileURLWithPath: "strings", isDirectory: true))
let catalogs = files.mapValues { LocalizedCatalog(strings: $0.strings) }
let strings = try DefaultStrings(configuration: StringsConfiguration(
  localizedStringSupplier: { catalogs },
  localeSupplier: { _ in locale },
  fallbackLocale: locale
))

let fr = try LocaleTag("fr")
assert(strings.supportedLocales.map(\.tag).sorted() == ["en", "fr"])
let matches20 = try strings.getKeysForLocale(locale).map(\.string).sorted() == ["Goodbye", "Hello"]
assert(matches20)
let matches21 = try strings.getMissingKeys(sourceLocale: locale, targetLocale: fr).map(\.string).sorted() == ["Goodbye"]
assert(matches21)

JavaScript

The getKeysForLocale(...) and getMissingKeys(...) methods are strict: an unsupported locale throws an UnsupportedLocaleError. Probe getSupportedLocales() first when availability is uncertain.

Java

The getKeysForLocale(...) and getMissingKeys(...) methods are strict: unsupported locales throw. Probe getSupportedLocales() first when availability is uncertain.

Swift

getKeysForLocale(...) and getMissingKeys(sourceLocale:targetLocale:) throw UnsupportedLocaleError for unsupported locales. Check supportedLocales when availability is uncertain. Keys are ExactString values, preserving distinct Unicode spellings.

JavaScript

Localized strings compilation and lookup run under fixed limits. They bound numeric work, expression parsing, recursive placeholder generation, interpolation, and cumulative expansion.

Java

Localized strings compilation and lookup use immutable TranslationRuntimeLimits. Defaults bound numeric work, expression parsing, recursive placeholder generation, interpolation, and cumulative expansion.

Swift

Immutable TranslationRuntimeLimits bound numeric work, expression parsing, recursive placeholder generation, interpolation, and cumulative expansion. Supply stricter limits through StringsConfiguration.runtimeLimits:

JavaScript

The JavaScript package fixes these limits at the defaults above. They cannot be configured: createStrings refuses a runtimeLimits option. The hard ceilings still apply while localized strings are loaded.

Java

TranslationRuntimeLimits runtimeLimits = TranslationRuntimeLimits.builder()
  .maximumExpressionCharacters(1_024)
  .maximumExpressionTokens(128)
  .maximumInterpolatedOutputCharacters(128 * 1_024)
  .maximumGeneratedExpansionCharacters(512 * 1_024)
  .build();

Strings strings = Strings.withFallbackLocale(Locale.ENGLISH)
  .localizedStringSupplier(() -> LocalizedStringLoader
    .loadFromClasspath("com/example/myapp/strings"))
  .localeSupplier(matcher -> Locale.ENGLISH)
  .runtimeLimits(runtimeLimits)
  .build();