Localization

Customize UI strings and add language support to the social.plus UIKit

The social.plus UIKit ships with built-in English strings and a localization API that lets you add any language — or override individual strings — without forking the UIKit. English is the only built-in language. Any key missing from a custom locale bundle automatically resolves to its English value — no errors are thrown and no code changes are needed.

Platform Implementation

Select your platform below for API details and integration code.

iOS (Swift)

How to Add a New Language

Option A — Bundle-based .lproj files (recommended)

Provide translations via standard iOS .lproj directories in your app bundle. The UIKit checks Bundle.main for AmityLocalizable.strings before falling back to its framework bundle — no code changes needed.

MyApp/
└── Resources/
    ├── en.lproj/AmityLocalizable.strings   ← English overrides (optional)
    └── ja.lproj/AmityLocalizable.strings   ← Japanese translations

/* ja.lproj/AmityLocalizable.strings */
"amity_common_button_cancel" = "キャンセル";
"amity_common_button_delete" = "削除";
"amity_social_button_comments" = "コメント";

iOS automatically selects the correct .lproj folder based on the device language. This approach follows the standard iOS localization pattern and is well-suited for teams where translation stakeholders are non-technical — they only need to edit .strings files without touching application code.

Use the English reference file AmityLocalizable.strings as the source of truth for all available keys.

Generate translations with AI: Download the English .strings file linked above and paste it into an AI assistant (ChatGPT, Claude, Copilot) with the prompt: “Translate all values to [language]. Keep all keys, format specifiers (%@, %d, %s), and file format unchanged.” This is a fast way to get a complete draft — have a native speaker review the output before shipping.

Option B — Programmatic via String Provider API

Provide a [String: String] dictionary of translated keys and register it with each provider at runtime.

1. Create a locale bundle

   Create a dictionary with the translated keys. You only need to include keys you’re translating — missing keys fall back to the built-in English values automatically.

   struct MyJapaneseStrings {
       static let social: [String: String] = [
           "amity_social_button_comments": "コメント",
           "amity_social_button_delete_comment": "コメントを削除",
           "amity_social_button_edit_comment": "コメントを編集",
       ]
   
       static let common: [String: String] = [
           "amity_common_button_cancel": "キャンセル",
           "amity_common_button_done": "完了",
       ]
   
       static let chat: [String: String] = [
           "amity_chat_edit_message": "メッセージを編集",
       ]
   }
   
2. Register the locale bundle

   Call setLocale on each provider — typically at app launch or in response to a user language-switch action:

   AmityStringProvider.social.setLocale("ja", bundle: MyJapaneseStrings.social)
   AmityStringProvider.common.setLocale("ja", bundle: MyJapaneseStrings.common)
   AmityStringProvider.chat.setLocale("ja", bundle: MyJapaneseStrings.chat)
   

   To revert to the default English strings:

   AmityStringProvider.social.deactivateLocale()
   AmityStringProvider.common.deactivateLocale()
   AmityStringProvider.chat.deactivateLocale()
   

Option C — Override individual keys

To replace specific strings without changing the whole language, use setOverrides(). Overrides merge on top of any active locale.

AmityStringProvider.social.setOverrides([
    "amity_social_button_comments": "Replies",
    "amity_social_modal_dialog_generic_error": "Something went wrong. Please try again.",
])

AmityStringProvider.common.setOverrides([
    "amity_common_button_cancel": "Dismiss",
])

To clear overrides:

AmityStringProvider.social.clearOverrides()
AmityStringProvider.common.clearOverrides()

Android (Kotlin)

How to Add a New Language

Option A — Android resource files (recommended)

Provide translations using standard Android resource directories in your app module. Since Android merges resources at build time, app-level strings override library-level strings automatically — no fork required.

Add values-<language-code>/strings.xml files in your app module with the same amity_* resource names used by the UIKit:

app/src/main/res/
├── values/strings.xml              ← your app's default strings (unchanged)
└── values-ja/strings.xml           ← Japanese translations for UIKit keys

<!-- app/src/main/res/values-ja/strings.xml -->
<resources>
    <string name="amity_common_button_cancel">キャンセル</string>
    <string name="amity_common_button_delete">削除</string>
    <string name="amity_social_button_comments">コメント</string>
</resources>

Android automatically selects the correct values-<lang>/ folder based on the device language. This approach follows the standard Android localization pattern and is well-suited for teams where translation stakeholders are non-technical — they only need to edit XML files without touching application code.

For the full key list, refer to the English default strings.xml files in the Android UIKit open source repository:

• social-compose/.../values/strings.xml (social keys)
• common-compose/.../values/strings.xml (common keys)

You can also refer to the comprehensive LOCALIZATION_GUIDE.md in the repository for detailed instructions and examples.

Generate translations with AI: Download the English strings.xml files linked above and paste them into an AI assistant (ChatGPT, Claude, Copilot) with the prompt: “Translate all values to [language]. Keep all keys, format specifiers (%s, %d, %1$s), and XML format unchanged.” This is a fast way to get a complete draft — have a native speaker review the output before shipping.

Option B — Locale bundle via String Provider API

Provide a Map<String, String> of translated keys and register it with the provider at runtime.

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:

   DefaultAmitySocialStringProvider.setLocale("ja", MyJapaneseStrings.social)
   DefaultAmityCommonStringProvider.setLocale("ja", MyJapaneseStrings.common)
   

   To revert to the default English resources:

   DefaultAmitySocialStringProvider.getInstance().clearLocale()
   DefaultAmityCommonStringProvider.getInstance().clearLocale()
   

Option C — Override individual keys

To replace specific strings without changing the whole language, use setOverrides(). Overrides 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",
))

To clear overrides:

DefaultAmitySocialStringProvider.getInstance().clearOverrides()
DefaultAmityCommonStringProvider.getInstance().clearOverrides()

Social keys start with amity_social_; common keys start with amity_common_. When calling provider methods, use the correct provider for each key prefix.

Web (React)

How to Add a New Language

1. Create a translation file

   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.

   {
     "amity_common_button_cancel": "キャンセル",
     "amity_common_button_delete": "削除",
     "amity_social_button_block_user": "ユーザーをブロック"
   }
   
2. Register via localeMap

   Pass the bundle via localeMap on AmityUIKitProvider so the UIKit auto-detects it from navigator.language:

   import jaLocale from './locales/ja.json';
   
   <AmityUIKitProvider
     localization={{
       localeMap: {
         ja: jaLocale,
       },
     }}
   >
     <App />
   </AmityUIKitProvider>
   

   The UIKit checks navigator.language — exact match first (e.g. "ja"), then language-prefix match (e.g. "ja-JP" → "ja"). Falls back to English if no match is found.

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.

   Generate translations with AI: Download the en.json file linked above and paste it into an AI assistant (ChatGPT, Claude, Copilot) with the prompt: “Translate all values to [language]. Keep all keys, format specifiers (%s, %d), and JSON format unchanged.” This is a fast way to get a complete draft — have a native speaker review the output before shipping.

Other Scenarios

Override specific strings

Use the overrides prop to replace individual keys without providing a full locale bundle. Overrides merge on top of the active locale.

<AmityUIKitProvider
  localization={{
    overrides: {
      'amity_common_button_cancel': 'Dismiss',
      'amity_social_button_delete_post_title': 'Remove this post?',
    },
  }}
>
  <App />
</AmityUIKitProvider>

Switch locale at runtime

useLocale controls the active locale. useString consumes strings and automatically re-renders all consumers when the locale changes.

import { useLocale, useString } from '@amityco/ui-kit';
import jaLocale from './locales/ja.json';

function LanguageSwitcher() {
  const { setLocaleBundle, clearLocaleBundle } = useLocale();

  return (
    <>
      <button onClick={() => setLocaleBundle(jaLocale)}>日本語</button>
      <button onClick={() => clearLocaleBundle()}>English</button>
    </>
  );
}

// Any child component — automatically re-renders on locale change
function CancelButton() {
  const label = useString('amity_common_button_cancel');
  return <button>{label}</button>;
}

Version alignment: New UIKit releases may introduce new localization keys for new UI components or features. When upgrading, re-generate your translation files from the open source reference file that matches your UIKit version to ensure no keys are missing. Untranslated keys fall back to English silently, but keeping your translation files up to date ensures a fully localized experience.

Migrating from config.json Text Overrides

config.json text overrides are deprecated for string customization. If you previously used config.json to override UI strings (e.g. button labels, error messages), you should migrate those overrides to the localization API described above — even if you don’t plan to add new languages.

Existing config.json text overrides are still resolved gracefully for now, but this auto-resolution may be removed in a future release. New UI components and features will only support string customization through the localization system.

config.json remains available for other configuration such as theme and UI element visibility — only string/text overrides are being deprecated.