Skip to content

Commit 7ddaf1b

Browse files
dzieniszAnty0
dzienisz
and
Anty0
authored
docs: add Android SDK documentation with installation and usage guides (#969)
https://github.com/tolgee/tolgee-mobile-kotlin-sdk <img width="1470" height="868" alt="Screenshot 2025-08-07 at 12 52 37" src="https://github.com/user-attachments/assets/50f9b28e-d5a3-4823-9302-97be388dec2c" /> <img width="1381" height="841" alt="Screenshot 2025-08-07 at 12 53 19" src="https://github.com/user-attachments/assets/a6a8acf4-174d-434e-9ec0-1bb61cea0615" /> --------- Co-authored-by: Jiří Kuchyňka (Anty) <[email protected]>
1 parent 9034029 commit 7ddaf1b

20 files changed

+857
-10
lines changed

‎android-sdk/about.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
id: about
3+
title: Overview
4+
slug: /
5+
description: Overview of Tolgee Android SDK with Over‑the‑Air (OTA) localization updates and how to get started.
6+
---
7+
8+
> NOTE:
9+
> For managing static translations in your repository, consider using the [Tolgee CLI](/tolgee-cli/installation).
10+
11+
Tolgee Android SDK lets you localize Android apps with dynamic content delivery, Over‑the‑Air (OTA) translation updates, reactive locale changes, and seamless integration with Views and Jetpack Compose.
12+
13+
## Why use it
14+
15+
- __Avoid releases for copy changes__: Ship translation fixes and new languages without a new app build.
16+
- __Faster iteration__: Product/localization teams can push improvements instantly and validate in production.
17+
- __Consistent UX__: UI updates reactively on locale change; fewer stale or mismatched strings.
18+
- __Resilient by default__: Works offline with caching and resource fallbacks; fewer blank strings.
19+
20+
## What you can do
21+
22+
- __Over‑the‑Air (OTA) updates__: Deliver translations via CDN (Cloud or self‑host) with caching.
23+
- __Views and Compose support__: `stringResource`/`pluralStringResource`, parameters, and reactive updates.
24+
- __Runtime locale API__: Switch locales and react to `Tolgee.changeFlow`.
25+
- __Fallbacks and preloading__: Android resources fallback; preload critical namespaces/locales.
26+
- __Hosting options__: Tolgee Cloud CDN or your own CDN.
27+
28+
## Demo apps
29+
30+
- __Android Views demo__: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/exampleandroid
31+
- __Jetpack Compose demo__: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplejetpack
32+
33+
## Compatibility
34+
35+
> NOTE:
36+
> Build configuration examples use Kotlin DSL (`build.gradle.kts`). Groovy DSL may work but is not officially supported/tested.
37+
38+
## Get started
39+
40+
- __Installation__: Set up dependencies and network security — [Installation](./installation.mdx)
41+
- __Modules overview__: Choose between Core and Compose — [Modules overview](./modules.mdx)
42+
- __Jetpack Compose__: Install, use, and troubleshoot — [Installation](/android-sdk/jetpack/installation), [Usage](/android-sdk/jetpack/usage), [Troubleshooting](/android-sdk/jetpack/troubleshooting)
43+
- __Usage with Views (non‑Compose)__: Simple keys, parameters, plurals, preloading, reactive flows — [Usage](./usage.mdx)
44+
- __Production guide__: Over‑the‑Air (OTA) updates, caching, formatting, testing — [Production guide](./production.mdx)
45+
- __Troubleshooting__: Common issues and diagnostics — [Troubleshooting](./troubleshooting.mdx)
46+
47+
## Next steps
48+
49+
- Install and configure the SDK: [Installation](./installation.mdx)
50+
- Connect your app to the Tolgee Platform and manage translations collaboratively: [Platform docs](../platform/)
51+
- Generate or manage static strings with CLI: [Tolgee CLI](/tolgee-cli/installation)

‎android-sdk/installation.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
id: installation
3+
title: Installation
4+
description: How to install Tolgee Android SDK in your Android project
5+
---
6+
7+
> **NOTE:**
8+
> For managing static translations, we recommend using [Tolgee CLI](https://github.com/tolgee/tolgee-cli).
9+
10+
## Requirements
11+
12+
- **Android API Level**: 21+ (Android 5.0+)
13+
14+
## Quickstart (Views)
15+
16+
1. Add dependency (Core):
17+
18+
Using Version Catalog is recommended to keep your versions aligned.
19+
20+
```toml
21+
# gradle/libs.versions.toml
22+
[libraries]
23+
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" }
24+
```
25+
26+
```kotlin
27+
// build.gradle.kts (module)
28+
dependencies {
29+
implementation(libs.tolgee)
30+
}
31+
```
32+
33+
If you use Jetpack Compose, see the Compose variant: [Jetpack Installation](/android-sdk/jetpack/installation)
34+
35+
2. (If needed) Ensure repositories include Maven Central:
36+
37+
```kotlin
38+
// settings.gradle.kts or build.gradle.kts
39+
pluginManagement { repositories { gradlePluginPortal(); google(); mavenCentral() } }
40+
dependencyResolutionManagement { repositories { google(); mavenCentral() } }
41+
```
42+
43+
3. Allow CDN networking (required when using Tolgee Cloud CDN):
44+
45+
Create a network security config file `network_security.xml` in your `res/xml` folder:
46+
47+
```xml
48+
<?xml version="1.0" encoding="utf-8"?>
49+
<network-security-config xmlns:android="http://schemas.android.com/apk/res/android">
50+
<domain-config>
51+
<domain includeSubdomains="true">tolgee.io</domain>
52+
<domain includeSubdomains="true">tolg.ee</domain>
53+
</domain-config>
54+
</network-security-config>
55+
```
56+
57+
Add network security config to your `AndroidManifest.xml`:
58+
59+
```xml
60+
<application
61+
android:networkSecurityConfig="@xml/network_security"> <!-- Add this line to your existing application tag -->
62+
</application>
63+
```
64+
65+
> NOTE:
66+
> Allowing `tolgee.io` and `tolg.ee` domains is required when using Tolgee Cloud CDN. If you only access your own self-hosted CDN, include your domain(s) accordingly.
67+
68+
## Initialization and configuration
69+
70+
Initialize Tolgee in your `Application` class.
71+
72+
```kotlin
73+
class MyApplication : Application() {
74+
override fun onCreate() {
75+
super.onCreate()
76+
Tolgee.init {
77+
contentDelivery {
78+
url = "https://cdn.tolg.ee/your-cdn-url-prefix" // from Tolgee Platform → Content Delivery
79+
storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
How to get your CDN URL prefix (Content Delivery):
87+
- Open Tolgee Platform → your Project → Developer settings → Content Delivery.
88+
- Copy the full CDN URL prefix. You can use different prefixes per environment (dev/staging/prod).
89+
- Optional: Verify connectivity locally:
90+
91+
```bash
92+
curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json"
93+
```
94+
95+
You should receive a 200 response. If you get 403/404, double‑check the prefix.
96+
97+
> TIP:
98+
> For Activities, wrap the base context so `getString` and similar APIs use Tolgee. See step-by-step in [Usage](./usage.mdx).
99+
100+
## Next steps
101+
102+
- Not sure which artifact to use? See [`Modules overview`](./modules.mdx)
103+
- Learn how to fetch and render translations in Views: [`Usage`](./usage.mdx)
104+
- Using Compose? Start here: [`Jetpack Installation`](./jetpack/installation.mdx)
105+
- Having issues? Check [`Troubleshooting`](./troubleshooting.mdx)
106+

‎android-sdk/jetpack/installation.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
id: installation
3+
title: Installation
4+
description: How to install Tolgee Android SDK in your Android project with Jetpack Compose support
5+
---
6+
7+
> **NOTE:**
8+
> For managing static translations, we recommend using [Tolgee CLI](https://github.com/tolgee/tolgee-cli).
9+
10+
## Requirements
11+
12+
- **Android API Level**: 21+ (Android 5.0+)
13+
14+
## Setup
15+
16+
Using Version Catalog is highly recommended to keep your versions aligned.
17+
18+
```toml
19+
# gradle/libs.versions.toml
20+
[libraries]
21+
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" }
22+
```
23+
24+
```kotlin
25+
// build.gradle.kts (module)
26+
dependencies {
27+
implementation(libs.tolgee)
28+
}
29+
```
30+
31+
Create a network security config file `network_security.xml` in your `res/xml` folder:
32+
33+
```xml
34+
<?xml version="1.0" encoding="utf-8"?>
35+
<network-security-config xmlns:android="http://schemas.android.com/apk/res/android">
36+
<domain-config>
37+
<domain includeSubdomains="true">tolgee.io</domain>
38+
<domain includeSubdomains="true">tolg.ee</domain>
39+
</domain-config>
40+
</network-security-config>
41+
```
42+
43+
Add network security config to your `AndroidManifest.xml`:
44+
45+
```xml
46+
<application
47+
android:networkSecurityConfig="@xml/network_security"> <!-- Add this line to your existing application tag -->
48+
</application>
49+
```
50+
51+
## Initialization
52+
53+
Initialize Tolgee in your Application class (Android). You can find your CDN URL prefix in the Tolgee Platform under your Project settings (CDN/Content Delivery). Use different prefixes per environment.
54+
55+
```kotlin
56+
class MyApplication : Application() {
57+
override fun onCreate() {
58+
super.onCreate()
59+
60+
Tolgee.init {
61+
contentDelivery {
62+
url = "https://cdn.tolg.ee/your-cdn-url-prefix" // e.g., from Tolgee Platform
63+
storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update
64+
}
65+
}
66+
}
67+
}
68+
```
69+
70+
> TIP:
71+
> Compose uses its own `stringResource`/`pluralStringResource` helpers, no `ContextWrapper` needed.
72+
73+
### Next steps
74+
75+
- Learn how to compose translations: [`Usage`](./usage.mdx)
76+
- Problems? See [`Troubleshooting`](./troubleshooting.mdx)

‎android-sdk/jetpack/troubleshooting.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
id: troubleshooting
3+
title: Troubleshooting
4+
description: Troubleshooting Tolgee Android SDK for Jetpack Compose
5+
---
6+
7+
## Translations Not Updating
8+
9+
- Ensure you're using the `stringResource` and `pluralStringResource` functions from the Tolgee package
10+
- Check that your Tolgee instance is properly initialized
11+
- Verify that the translations are loaded correctly (preload or make sure you're using flow-based API - `tFlow` / `stringResource`)
12+
13+
## Android Resource Integration Issues
14+
15+
- Check that your Android resources are properly structured - Tolgee is using `resources.getResourceEntryName` to find key for the resource
16+
- Ensure that the Tolgee instance has access to the Android context
17+
18+
## Compose Multiplatform Issues
19+
20+
- Verify that your resource files are correctly set up and all keys present in resources are present in a Tolgee platform too
21+
- Ensure that you're using the correct resource references
22+
23+
## Best practices for Compose
24+
25+
- Hoist Tolgee instance at the application level; avoid creating it in composables.
26+
- Use `collectAsState` on `changeFlow` to recompose on locale/translation updates.
27+
- Prefer `stringResource`/`pluralStringResource` helpers for readability.
28+
29+
## CDN/Network
30+
31+
- If using Tolgee Cloud, ensure `tolgee.io` and `tolg.ee` are allowed in `res/xml/network_security.xml` and referenced via `android:networkSecurityConfig`.
32+
- For self‑hosting, replace the CDN URL with your domain and allow it in `network_security.xml`.
33+
- Quick connectivity test:
34+
35+
```bash
36+
curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json"
37+
```
38+
39+
## Useful links
40+
41+
- Views troubleshooting: [/android-sdk/troubleshooting](/android-sdk/troubleshooting)
42+
- Installation (Compose): [Installation](./installation.mdx)
43+
- Usage (Compose): [Usage](./usage.mdx)
44+

‎android-sdk/jetpack/usage.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
id: usage
3+
title: Usage
4+
description: How to use Tolgee Android SDK in your Android application with Jetpack Compose support
5+
---
6+
7+
> Prerequisite: Make sure you’ve installed and initialized the Tolgee for Compose. See: [Jetpack Compose Installation](./installation.mdx)
8+
9+
Tolgee’s Jetpack Compose extensions let you fetch localized strings directly inside your composables. Below are the most common patterns you’ll use:
10+
11+
* __Use `stringResource` for simple strings__ - retrieve a translation by its resource ID.
12+
13+
```kotlin
14+
@Composable
15+
fun SimpleText() {
16+
Text(text = stringResource(R.string.welcome_message))
17+
}
18+
```
19+
* __Pass parameters to translations__ - supply arguments for placeholders in your strings.
20+
21+
```kotlin
22+
@Composable
23+
fun TextWithParameters(name: String) {
24+
Text(text = stringResource(R.string.welcome_user, name))
25+
}
26+
```
27+
* __Handle plurals with `pluralStringResource`__ - provide the count and any formatting args.
28+
29+
```kotlin
30+
@Composable
31+
fun PluralText(count: Int) {
32+
Text(text = pluralStringResource(R.plurals.item_count, count, count))
33+
}
34+
```
35+
36+
## Explicit Tolgee Instance
37+
38+
If you need to use a specific Tolgee instance (not the singleton), you can pass it explicitly:
39+
40+
```kotlin
41+
@Composable
42+
fun ExplicitInstance() {
43+
val tolgee = remember { myCustomTolgee }
44+
45+
Text(text = stringResource(tolgee, R.string.welcome_message))
46+
}
47+
```
48+
49+
## Locale Switching
50+
51+
You can create a locale switcher component:
52+
53+
```kotlin
54+
@Composable
55+
fun LocaleSwitcher() {
56+
val tolgee = Tolgee.instance
57+
val locale by tolgee.changeFlow
58+
.map { tolgee.getLocale() }
59+
.collectAsState(initial = tolgee.getLocale())
60+
61+
Row {
62+
Text(text = stringResource(tolgee, R.string.selected_locale, locale.language))
63+
Button(onClick = { tolgee.setLocale("en") }) {
64+
Text("English")
65+
}
66+
Button(onClick = { tolgee.setLocale("fr") }) {
67+
Text("Français")
68+
}
69+
Button(onClick = { tolgee.setLocale("cs") }) {
70+
Text("Čeština")
71+
}
72+
}
73+
}
74+
```
75+
76+
## Observing Locale Changes
77+
78+
Collecting `Tolgee.changeFlow` as state ensures your composable recomposes whenever the locale changes, keeping the UI in sync with the active language.
79+
80+
```kotlin
81+
@Composable
82+
fun LocaleAwareComponent() {
83+
val tolgee = Tolgee.instance
84+
85+
val locale by tolgee.changeFlow
86+
.map { tolgee.getLocale() }
87+
.collectAsState(initial = tolgee.getLocale())
88+
89+
Text(text = locale.language)
90+
}
91+
```
92+
93+
## Next steps
94+
95+
- Learn the basics with Views: [`Usage`](/android-sdk/usage)
96+
- Problems? See [`Troubleshooting`](/android-sdk/jetpack/troubleshooting)

0 commit comments

Comments
 (0)