The Web UIKit v4 resolves every UI string through a 5-level priority chain. Higher levels win; missing keys fall through to the next level automatically.
Priority
Level
Source
Highest
1
Config text via CustomizationProvider (remote config)
2
Programmatic key overrides (overrides prop)
3
Locale bundle (localeBundle prop or localeMap auto-detection)
The UIKit checks navigator.language — exact match first (e.g. "th"), then language-prefix match (e.g. "th-TH" → "th"). Falls back to English if no match is found.
Create a flat JSON file with the keys you want to translate. You only need to include keys you’re translating — missing keys automatically fall back to English.
Pass the bundle via localeMap so the UIKit auto-detects it from navigator.language:
import jaLocale from './locales/ja.json';import { thLocaleBundle } from '@amityco/ui-kit';<AmityUIKitProvider localization={{ localeMap: { th: thLocaleBundle, // preserve built-in Thai auto-detection ja: jaLocale, // add Japanese }, }}> <App /></AmityUIKitProvider>
Providing localeMap replaces the default locale map entirely. Include th: thLocaleBundle explicitly if you want to preserve built-in Thai auto-detection alongside your new language.
3
Verify coverage
Compare your translation file against en.json to identify missing keys. Any untranslated key silently falls back to English — no errors are thrown.
The iOS UIKit ships with English strings in AmityLocalizable.strings inside the framework bundle. Localization works through the standard iOS bundle/.lproj mechanism. There is no dedicated setLanguage() API — string resolution happens automatically based on the device language.At runtime, the UIKit checks your main app bundle for an AmityLocalizable.strings file before falling back to its built-in English strings. This means you can add or override translations directly in your app project without forking the UIKit.Strings are accessed internally via the AmityLocalizedStringSet enum and the .localizedString computed property on String:
// Internal usage (for reference)AmityLocalizedStringSet.General.ok.localizedString// Resolves via: NSLocalizedString(key, tableName: "AmityLocalizable", bundle: ...)// Checks main app bundle first, then falls back to the framework bundle
In your Xcode project, create .lproj folders for each language you want to support and add an AmityLocalizable.strings file inside each one. For example, to add Japanese:
MyApp/└── Resources/ ├── en.lproj/AmityLocalizable.strings ← English overrides (optional) └── ja.lproj/AmityLocalizable.strings ← Japanese translations
Make sure the files are added to your app target in Xcode.
2
Translate the strings
Use the same keys as the UIKit’s built-in English strings and provide translated values:
You only need to include keys you are translating — any key not found in your file automatically falls back to the UIKit’s built-in English value.
3
Run your app
No code changes are needed. iOS automatically selects the correct .lproj folder based on the device language, and the UIKit loads strings from your app bundle at runtime.
For the full key list, refer to AmityLocalizable.strings in the open source repository. Use this as the reference for all available keys and their default English values when building your translations.
The Android UIKit v4 resolves every UI string through a 3-level priority chain. Higher levels win; missing keys fall through to the next level automatically.
Priority
Level
Source
Highest
1
Programmatic key overrides (setOverrides())
2
Active locale bundle (setLocale())
Lowest
3
Android string resources (strings.xml — English default)
String resolution is handled by two providers: DefaultAmitySocialStringProvider (social strings) and DefaultAmityCommonStringProvider (common strings). Both providers are singletons initialized in your Application.onCreate().
Option A — Locale bundle via String Provider API (recommended)
Provide a Map<String, String> of translated keys and register it with the provider. No fork required.
1
Initialize the providers
Call both providers in your Application.onCreate():
class MyApplication : Application() { override fun onCreate() { super.onCreate() DefaultAmitySocialStringProvider.initialize(this) DefaultAmityCommonStringProvider.initialize(this) }}
2
Create a locale bundle
Create a Kotlin object (or a plain Map<String, String>) with the translated keys. You only need to include keys you’re translating — missing keys fall back to the English strings.xml values automatically.
object MyJapaneseStrings { val social: Map<String, String> = mapOf( "amity_social_button_comments" to "コメント", "amity_social_button_delete_comment" to "コメントを削除", "amity_social_button_edit_comment" to "コメントを編集", ) val common: Map<String, String> = mapOf( "amity_common_button_cancel" to "キャンセル", "amity_common_button_done" to "完了", )}
3
Register the locale bundle
Call setLocale() on both providers — typically in Application.onCreate() after initialization, or in response to a user language-switch action:
To replace specific strings without providing a full locale bundle, use setOverrides(). Overrides take the highest priority and merge on top of any active locale.
DefaultAmitySocialStringProvider.setOverrides(mapOf( "amity_social_button_comments" to "Replies", "amity_social_modal_dialog_generic_error" to "Something went wrong. Please try again.",))DefaultAmityCommonStringProvider.setOverrides(mapOf( "amity_common_button_cancel" to "Dismiss",))
For full static translation using the Android resource system, clone the UIKit and add values-<language-code>/ resource directories inside each module:
// String substitution"amity_social_label_created_by" to "By %s"// Integer substitution"amity_social_label_follow_requests" to "Follow requests (%1$d)"// Multiple arguments"amity_social_error_post_text_exceed_error_message" to "Post text exceeds the %1$d characters limit"
Keys are shared between DefaultAmitySocialStringProvider (social strings, ~1005 keys) and DefaultAmityCommonStringProvider (common strings, ~49 keys). Social keys start with amity_social_; common keys start with amity_common_. When overriding, use the correct provider for each key prefix.
For the full key list, refer to AmitySocialStrings.kt and AmityCommonStrings.kt in the Android UIKit source repository, or see the sample Thai locale bundle in sample/src/main/java/.../localization/AmitySocialThaiStrings.kt as a complete override example.
