App Localization CLI (ALC)

A simple CLI tool for managing app localizations for iOS and Android projects using Capacitor or Cordova.

Features

📱 iOS & Android Support
🔄 Automatic Resource Updates
🌐 Multiple Language Support
⚡️ Easy to Use

Apps use ALC

- AcuNote: Acupuncture and Meridian points learning app.
- W3S: Easy frontend tutorials for beginners.
- Classical Chinese: Learn Classical Chinese Easily.
- Style Rater: Meet Your Better Self!
- Chinese Meal: Chinese Vegetarian Cuisine Guide.
- Welcome to add your app here...

Installation & Usage

No installation needed! Just run with npx:

``bash
npx app-localization-cli
`

Or install globally if you prefer:

`bash
npm install -g app-localization-cli
update-localizations
`

Project Structure

Your project should look like this:

`
your-project/
├── localizations/ # Your localization configs
│ ├── en.json
│ ├── zh-Hans.json
│ └── zh-Hant.json
├── ios/ # iOS project directory
│ └── App/
│ ├── App/
│ │ ├── Info.plist
│ │ ├── en.lproj/
│ │ ├── zh-Hans.lproj/
│ │ └── zh-Hant.lproj/
│ └── App.xcodeproj/
│ └── project.pbxproj
└── android/ # Android project directory
└── app/
└── src/
└── main/
└── res/
├── values/
│ └── strings.xml
├── values-zh-rCN/
│ └── strings.xml
└── values-zh-rTW/
└── strings.xml
`

Configuration

$3

Create JSON files in the localizations directory for each language:

📄 localizations/en.json:

`json
{
"ios": {
"CFBundleDisplayName": "My App"
},
"android": {
"title_activity_main": "My App"
}
}
`

📄 localizations/zh-Hans.json:

`json
{
"ios": {
"CFBundleDisplayName": "我的应用"
},
"android": {
"title_activity_main": "我的应用"
}
}
`

$3

`bash


Update both platforms

npx app-localization-cli

Or update specific platform

npx app-localization-cli --platform ios
npx app-localization-cli --platform android
`

How It Works

$3

1. Creates .lproj directories for each language
2. Generates InfoPlist.strings files with localized values
3. Updates Info.plist to add CFBundleLocalizations and CFBundleDevelopmentRegion localizations values
4. Updates Xcode project configuration to include new languages

Example iOS output:

`
MyApp/
├── en.lproj/
│ └── InfoPlist.strings # CFBundleDisplayName = "My App";
├── zh-Hans.lproj/
│ └── InfoPlist.strings # CFBundleDisplayName = "我的应用";
└── Info.plist # CFBundleDisplayName = "My App";
`

$3

1. Creates values-* directories for each language
2. Generates or updates strings.xml files
3. Preserves existing string resources
4. Handles XML escaping automatically

Example Android output:

`
res/
├── values/
│ └── strings.xml # My App
└── values-zh-rCN/
└── strings.xml # 我的应用
`

Supported Keys

$3

| Key | Description |
| --------------------- | ------------------------ |
| CFBundleDisplayName | App name shown on device |
| ... | Any string resource |

$3

| Key | Description |
| --------------------- | ------------------- |
| title_activity_main | Application title |
| ... | Any string resource |

Language Code Mapping

| Language | iOS Code | Android Code |
| ------------------- | --------- | ------------------------------------------------- |
| English | en | values |
| Simplified Chinese | zh-Hans | values-zh-rCN |
| Traditional Chinese | zh-Hant | values-zh-rTW, values-zh-rHK, values-zh-rMO |
| Other Languages | ... | ... |

Troubleshooting

$3

1. NSUserTrackingUsageDescription is empty after build

Set a default value for NSUserTrackingUsageDescription in Info.plist.
Otherwise, it will be empty after build in CFBundleDevelopmentRegion language.

2. Files Not Updated

`bash
# Check if localizations directory exists
ls localizations/*.json

# Verify file permissions
ls -l ios/App/App
ls -l android/app/src/main/res
`

3. Wrong Directory Structure

`bash
# Should be in project root
npx app-localization-cli --help
`

4. Invalid JSON Format
`bash
# Validate JSON files
cat localizations/*.json | jq '.'
`

$3

`bash


Run with debug output


DEBUG=true npx app-localization-cli
``

License

MIT