diff --git a/android-sdk/about.mdx b/android-sdk/about.mdx deleted file mode 100644 index 202df6c02..000000000 --- a/android-sdk/about.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: about -title: Overview -slug: / -description: Overview of Tolgee Android SDK with Over‑the‑Air (OTA) localization updates and how to get started. ---- - -> NOTE: -> For managing static translations in your repository, consider using the [Tolgee CLI](/tolgee-cli/installation). - -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. - -## Why use it - -- __Avoid releases for copy changes__: Ship translation fixes and new languages without a new app build. -- __Faster iteration__: Product/localization teams can push improvements instantly and validate in production. -- __Consistent UX__: UI updates reactively on locale change; fewer stale or mismatched strings. -- __Resilient by default__: Works offline with caching and resource fallbacks; fewer blank strings. - -## What you can do - -- __Over‑the‑Air (OTA) updates__: Deliver translations via CDN (Cloud or self‑host) with caching. -- __Views and Compose support__: `stringResource`/`pluralStringResource`, parameters, and reactive updates. -- __Runtime locale API__: Switch locales and react to `Tolgee.changeFlow`. -- __Fallbacks and preloading__: Android resources fallback; preload critical namespaces/locales. -- __Hosting options__: Tolgee Cloud CDN or your own CDN. - -## Demo apps - -- __Android Views demo__: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/exampleandroid -- __Jetpack Compose demo__: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplejetpack - -## Compatibility - -> NOTE: -> Build configuration examples use Kotlin DSL (`build.gradle.kts`). Groovy DSL may work but is not officially supported/tested. - -## Get started - -- __Installation__: Set up dependencies and network security — [Installation](./installation.mdx) -- __Modules overview__: Choose between Core and Compose — [Modules overview](./modules.mdx) -- __Jetpack Compose__: Install, use, and troubleshoot — [Installation](/android-sdk/jetpack/installation), [Usage](/android-sdk/jetpack/usage), [Troubleshooting](/android-sdk/jetpack/troubleshooting) -- __Usage with Views (non‑Compose)__: Simple keys, parameters, plurals, preloading, reactive flows — [Usage](./usage.mdx) -- __Production guide__: Over‑the‑Air (OTA) updates, caching, formatting, testing — [Production guide](./production.mdx) -- __Troubleshooting__: Common issues and diagnostics — [Troubleshooting](./troubleshooting.mdx) - -## Next steps - -- Install and configure the SDK: [Installation](./installation.mdx) -- Connect your app to the Tolgee Platform and manage translations collaboratively: [Platform docs](../platform/) -- Generate or manage static strings with CLI: [Tolgee CLI](/tolgee-cli/installation) diff --git a/android-sdk/example-apps.mdx b/android-sdk/example-apps.mdx new file mode 100644 index 000000000..191969b13 --- /dev/null +++ b/android-sdk/example-apps.mdx @@ -0,0 +1,87 @@ +--- +id: example-apps +title: Example Apps +slug: /example-apps +description: Example apps for Tolgee Android SDK with Over‑the‑Air (OTA) localization updates for Android and Compose Multiplatform. +--- + +import { ScreenshotWrapper } from '../platform/shared/_ScreenshotWrapper'; + +# Example Apps + +Explore fully functional demo applications showcasing Tolgee Android SDK integration. Each example demonstrates best practices for implementing Over-the-Air translation updates in different Android development environments. + + + +## Android Views Demo + +**Perfect for traditional Android development** + +A complete reference implementation using classic Android Views and XML layouts. This example demonstrates: + +- ✅ One-time and dynamic translation methods +- ✅ Locale switching and change detection +- ✅ Integration with Android string resources +- ✅ Parameter support for dynamic content +- ✅ Proper Application-level initialization + +**[View Android Views Example →](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/exampleandroid)** + +--- + +## Jetpack Compose Demo + +**Modern declarative UI with reactive translations** + +A comprehensive example showcasing Tolgee integration with Jetpack Compose. Features include: + +- ✅ `stringResource()` composables for direct translation +- ✅ Parameter support for dynamic content +- ✅ Reactive UI updates when locale changes +- ✅ Formatter configuration options +- ✅ Integration with Compose state system + +**[View Jetpack Compose Example →](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplejetpack)** + +--- + +## Compose Multiplatform Demo + +**Cross-platform translations for Android, iOS, and Desktop** + +A full-featured multiplatform application demonstrating Tolgee's Kotlin Multiplatform capabilities: + +- ✅ Shared translation logic across platforms +- ✅ Compose Multiplatform UI integration +- ✅ Cross-platform resource handling +- ✅ Common API for all supported platforms +- ✅ Multiplatform development patterns + +**[View Compose Multiplatform Example →](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplecomposemultiplatform)** + +--- + +## Getting Started with Examples + +1. **Clone the repository**: + +```bash +git clone https://github.com/tolgee/tolgee-mobile-kotlin-sdk.git +``` +2. **Navigate to the demo folder**: Choose the example that matches your tech stack +3. **Open in Android Studio**: Import the project and sync Gradle +4. **Configure your CDN URL**: Add your Tolgee project's CDN URL in the initialization code +5. **Run and explore**: See live translation updates in action + +:::tip +These examples are actively maintained and updated with each SDK release. They're the best way to learn Tolgee integration patterns and troubleshoot issues. +::: + +## Next Steps + +- **New to Tolgee?** Start with [Installation](./installation) +- **Need help?** Check [Troubleshooting](./troubleshooting) + diff --git a/android-sdk/installation.mdx b/android-sdk/installation.mdx index 35eac6c1b..0013f2d9e 100644 --- a/android-sdk/installation.mdx +++ b/android-sdk/installation.mdx @@ -1,48 +1,71 @@ --- id: installation title: Installation -description: How to install Tolgee Android SDK in your Android project +description: Installation guide for Tolgee Android SDK --- -> **NOTE:** -> For managing static translations, we recommend using [Tolgee CLI](https://github.com/tolgee/tolgee-cli). +import AndroidApiRequirement from '@site/src/component/AndroidApiRequirement'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +:::note +Configuration examples below are written in Kotlin DSL. Groovy DSL should work but is not officially supported/tested. +::: ## Requirements -- **Android API Level**: 21+ (Android 5.0+) + -## Quickstart (Views) +## Setup dependencies -1. Add dependency (Core): +To use the library, you need to add the dependency to your project. - Using Version Catalog is recommended to keep your versions aligned. +In `gradle/libs.versions.toml` add an alias for Tolgee Core library: - ```toml - # gradle/libs.versions.toml - [libraries] - tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" } - ``` +:::info +Using **Version Catalog** is recommended to keep your versions aligned, especially in bigger projects. +This **provides readability, centralization, and consistency**. +::: - ```kotlin - // build.gradle.kts (module) - dependencies { - implementation(libs.tolgee) - } - ``` + + +```toml +[libraries] +tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" } +``` + + +```toml +[libraries] +tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" } +``` + + - If you use Jetpack Compose, see the Compose variant: [Jetpack Installation](/android-sdk/jetpack/installation) -2. (If needed) Ensure repositories include Maven Central: +Then, in `build.gradle.kts`, use the created alias: - ```kotlin - // settings.gradle.kts or build.gradle.kts - pluginManagement { repositories { gradlePluginPortal(); google(); mavenCentral() } } - dependencyResolutionManagement { repositories { google(); mavenCentral() } } - ``` -3. Allow CDN networking (required when using Tolgee Cloud CDN): +```kotlin +dependencies { + implementation(libs.tolgee) +} +``` - Create a network security config file `network_security.xml` in your `res/xml` folder: +:::info +The Compose module includes Core transitively, so you don't need to add both. +::: + +## Network Configuration + +Enable Tolgee to fetch translations from the cloud at runtime. To do this, you need to configure network access. + +Create a network security config file `network_security.xml` in your `res/xml` folder: ```xml @@ -54,53 +77,23 @@ description: How to install Tolgee Android SDK in your Android project ``` +In Android, the network security config must be explicitly linked in your `AndroidManifest.xml`, so the system knows to apply it. + Add network security config to your `AndroidManifest.xml`: ```xml + android:networkSecurityConfig="@xml/network_security"> ``` -> NOTE: -> 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. - -## Initialization and configuration - -Initialize Tolgee in your `Application` class. - -```kotlin -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - Tolgee.init { - contentDelivery { - url = "https://cdn.tolg.ee/your-cdn-url-prefix" // from Tolgee Platform → Content Delivery - storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update - } - } - } -} -``` - -How to get your CDN URL prefix (Content Delivery): -- Open Tolgee Platform → your Project → Developer settings → Content Delivery. -- Copy the full CDN URL prefix. You can use different prefixes per environment (dev/staging/prod). -- Optional: Verify connectivity locally: - -```bash -curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json" -``` - -You should receive a 200 response. If you get 403/404, double‑check the prefix. - -> TIP: -> For Activities, wrap the base context so `getString` and similar APIs use Tolgee. See step-by-step in [Usage](./usage.mdx). - -## Next steps +:::info +Allowing `tolgee.io` and `tolg.ee` domains is required when using Tolgee Cloud CDN. +If you access your own self-hosted CDN, here is where you should add the domain of your CDN. +::: -- Not sure which artifact to use? See [`Modules overview`](./modules.mdx) -- Learn how to fetch and render translations in Views: [`Usage`](./usage.mdx) -- Using Compose? Start here: [`Jetpack Installation`](./jetpack/installation.mdx) -- Having issues? Check [`Troubleshooting`](./troubleshooting.mdx) +## Next Steps +- Setup Tolgee Android SDK: [Setup](./setup.mdx) +- Learn how to fetch and render translations in Views: [Usage](./usage.mdx) +- Having issues? Check [Troubleshooting](./troubleshooting.mdx) diff --git a/android-sdk/jetpack/installation.mdx b/android-sdk/jetpack/installation.mdx deleted file mode 100644 index 9fb53abe2..000000000 --- a/android-sdk/jetpack/installation.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: installation -title: Installation -description: How to install Tolgee Android SDK in your Android project with Jetpack Compose support ---- - -> **NOTE:** -> For managing static translations, we recommend using [Tolgee CLI](https://github.com/tolgee/tolgee-cli). - -## Requirements - -- **Android API Level**: 21+ (Android 5.0+) - -## Setup - -Using Version Catalog is highly recommended to keep your versions aligned. - -```toml -# gradle/libs.versions.toml -[libraries] -tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" } -``` - -```kotlin -// build.gradle.kts (module) -dependencies { - implementation(libs.tolgee) -} -``` - -Create a network security config file `network_security.xml` in your `res/xml` folder: - -```xml - - - - tolgee.io - tolg.ee - - -``` - -Add network security config to your `AndroidManifest.xml`: - -```xml - - -``` - -## Initialization - -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. - -```kotlin -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - - Tolgee.init { - contentDelivery { - url = "https://cdn.tolg.ee/your-cdn-url-prefix" // e.g., from Tolgee Platform - storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update - } - } - } -} -``` - -> TIP: -> Compose uses its own `stringResource`/`pluralStringResource` helpers, no `ContextWrapper` needed. - -### Next steps - -- Learn how to compose translations: [`Usage`](./usage.mdx) -- Problems? See [`Troubleshooting`](./troubleshooting.mdx) \ No newline at end of file diff --git a/android-sdk/jetpack/troubleshooting.mdx b/android-sdk/jetpack/troubleshooting.mdx deleted file mode 100644 index a89311b70..000000000 --- a/android-sdk/jetpack/troubleshooting.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting -description: Troubleshooting Tolgee Android SDK for Jetpack Compose ---- - -## Translations Not Updating - -- Ensure you're using the `stringResource` and `pluralStringResource` functions from the Tolgee package -- Check that your Tolgee instance is properly initialized -- Verify that the translations are loaded correctly (preload or make sure you're using flow-based API - `tFlow` / `stringResource`) - -## Android Resource Integration Issues - -- Check that your Android resources are properly structured - Tolgee is using `resources.getResourceEntryName` to find key for the resource -- Ensure that the Tolgee instance has access to the Android context - -## Compose Multiplatform Issues - -- Verify that your resource files are correctly set up and all keys present in resources are present in a Tolgee platform too -- Ensure that you're using the correct resource references - -## Best practices for Compose - -- Hoist Tolgee instance at the application level; avoid creating it in composables. -- Use `collectAsState` on `changeFlow` to recompose on locale/translation updates. -- Prefer `stringResource`/`pluralStringResource` helpers for readability. - -## CDN/Network - -- If using Tolgee Cloud, ensure `tolgee.io` and `tolg.ee` are allowed in `res/xml/network_security.xml` and referenced via `android:networkSecurityConfig`. -- For self‑hosting, replace the CDN URL with your domain and allow it in `network_security.xml`. -- Quick connectivity test: - -```bash -curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json" -``` - -## Useful links - -- Views troubleshooting: [/android-sdk/troubleshooting](/android-sdk/troubleshooting) -- Installation (Compose): [Installation](./installation.mdx) -- Usage (Compose): [Usage](./usage.mdx) - diff --git a/android-sdk/jetpack/usage.mdx b/android-sdk/jetpack/usage.mdx index 57d845783..073900a18 100644 --- a/android-sdk/jetpack/usage.mdx +++ b/android-sdk/jetpack/usage.mdx @@ -1,14 +1,31 @@ --- id: usage -title: Usage -description: How to use Tolgee Android SDK in your Android application with Jetpack Compose support +title: Usage (Compose Module) +description: How to use Tolgee Android SDK Compose module in Jetpack Compose and Compose Multiplatform applications --- -> Prerequisite: Make sure you’ve installed and initialized the Tolgee for Compose. See: [Jetpack Compose Installation](./installation.mdx) +# Usage (Compose Module) -Tolgee’s Jetpack Compose extensions let you fetch localized strings directly inside your composables. Below are the most common patterns you’ll use: +This guide shows you how to use the Tolgee Android SDK Compose module in Jetpack Compose and Compose Multiplatform applications. For traditional Android Views usage, see [Android Views Usage](../usage.mdx). -* __Use `stringResource` for simple strings__ - retrieve a translation by its resource ID. +## Prerequisites + +**Make sure you've completed the quickstart setup and initialized Tolgee for Compose.** See: [Installation (Compose Module)](/android-sdk/installation.mdx) + +## Basic Usage + +Tolgee's Compose extensions let you fetch localized keys directly inside your composables. Unlike traditional Android Views which require manual UI updates or Activity recreation, Compose integration automatically recomposes UI elements when translations change. + +:::note +If you are unsure of which translation type to choose, notice a “Use for...” section under every explanation. +::: + + +## Getting translations + +### Simple Strings + +- **Jetpack Compose** ```kotlin @Composable @@ -16,7 +33,27 @@ fun SimpleText() { Text(text = stringResource(R.string.welcome_message)) } ``` -* __Pass parameters to translations__ - supply arguments for placeholders in your strings. + +- **Compose Multiplatform** + +```kotlin +@Composable +fun SimpleText() { + Text(text = stringResource(Res.string.welcome_message)) +} +``` + +:::info +In the Compose Multiplatform use `stringResource` function with `Res`. +::: + +Use `stringResource` for **simple strings** (e. g., error messages, titles), retrieve a translation by its resource ID. + +### With Parameters + +Pass parameters to translations, supply arguments for placeholders in your keys. + +- **Jetpack Compose** ```kotlin @Composable @@ -24,18 +61,60 @@ fun TextWithParameters(name: String) { Text(text = stringResource(R.string.welcome_user, name)) } ``` -* __Handle plurals with `pluralStringResource`__ - provide the count and any formatting args. + +- **Compose Multiplatform** + +```kotlin +@Composable +fun TextWithParameters(name: String) { + Text(text = stringResource(Res.string.welcome_user, name)) +} +``` + +Use for translation with **dynamic values**. Add data that changes during the app's runtime (e.g., dates, numbers, usernames). + +### Plurals + +Handle plurals with `pluralStringResource` - provide the count and any formatting arguments. + +- **Jetpack Compose** ```kotlin @Composable fun PluralText(count: Int) { - Text(text = pluralStringResource(R.plurals.item_count, count, count)) + // First 'count' parameter determines which plural form to use + // Second 'count' parameter is passed as a value to the translation + Text(text = pluralStringResource(R.plurals.items_count, count, count)) } ``` -## Explicit Tolgee Instance +- **Compose Multiplatform** + +```kotlin +@Composable +fun PluralText(count: Int) { + Text(text = pluralStringResource(Res.plurals.items_count, count, count)) +} +``` -If you need to use a specific Tolgee instance (not the singleton), you can pass it explicitly: +**Example plural resource:** + +```xml + + + %d item + %d items + +``` + +The `pluralStringResource` function will: +1. Select the correct plural form based on the count value +2. Replace the placeholder with the provided value +3. Automatically update the UI if the count changes or if translations are updated + +**Use for lists, counters, notifications** — any situation where the grammar changes with quantity. + +## Explicit Tolgee Instance ```kotlin @Composable @@ -46,20 +125,22 @@ fun ExplicitInstance() { } ``` +Handy when you need **more than one instance** (multiple projects/CDNs), when following **dependency injection** patterns (dependencies are “injected”, not created inside classes), and or **during testing/previews**. + ## Locale Switching -You can create a locale switcher component: +**You can create a locale switcher component:** ```kotlin @Composable fun LocaleSwitcher() { val tolgee = Tolgee.instance - val locale by tolgee.changeFlow - .map { tolgee.getLocale() } - .collectAsState(initial = tolgee.getLocale()) + val currentLocale = tolgee.changeFlow.mapLatest { + tolgee.getLocale() + }.collectAsState(initial = tolgee.getLocale()) Row { - Text(text = stringResource(tolgee, R.string.selected_locale, locale.language)) + Text(text = stringResource(tolgee, R.string.selected_locale, currentLocale.language)) Button(onClick = { tolgee.setLocale("en") }) { Text("English") } @@ -72,10 +153,13 @@ fun LocaleSwitcher() { } } ``` +Handy for apps, where “**choose language**” option is available, you want to use **Over‑the‑Air (OTA) translation updates** (translations refresh automatically when locale or content changes), and during **testing/debugging**. +Most often used in **settings screens, onboarding flows, or debug menus** - anytime you want to allow **runtime language switching**. ## Observing Locale Changes -Collecting `Tolgee.changeFlow` as state ensures your composable recomposes whenever the locale changes, keeping the UI in sync with the active language. +**Collecting `Tolgee.changeFlow` as state ensures your composable recomposes whenever the locale changes**, +keeping the UI in sync with the active language. ```kotlin @Composable @@ -90,7 +174,31 @@ fun LocaleAwareComponent() { } ``` -## Next steps +Handy for **observing locale changes** in real time, **keeping track of current locale**, **showing chosen language** in app, **reactively updating translations** whenever user switches the language. + +## How Compose Integration Differs from Android Views + +Tolgee's Compose integration offers several advantages over traditional Android Views: + +**Reactive by default** - Compose UI automatically updates when translations change, without manual intervention + +**No Activity recreation needed** - Unlike Android Views which require `recreate()` to refresh translations + +**Simplified API** - Familiar `stringResource()` and `pluralStringResource()` functions that match Compose's built-in functions + +**State-based** - Translations are part of the Compose state system, ensuring proper recomposition + +**Multiplatform support** - Works with both Jetpack Compose for Android and Compose Multiplatform + +## Example Projects + +For complete examples of how to use the Tolgee Compose module, check out the demo projects: + +- **[Example Jetpack](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplejetpack)** - Jetpack Compose example +- **[Multiplatform Compose](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/examplecomposemultiplatform)** - Compose Multiplatform example + +## Next Steps -- Learn the basics with Views: [`Usage`](/android-sdk/usage) -- Problems? See [`Troubleshooting`](/android-sdk/jetpack/troubleshooting) +- **Using traditional Views?** See [Android Views Usage](../usage.mdx) +- **Having issues?** Check [Troubleshooting](../troubleshooting.mdx) +- **Need example apps?** See [Example Apps](../example-apps.mdx) diff --git a/android-sdk/modules.mdx b/android-sdk/modules.mdx deleted file mode 100644 index 372aa8447..000000000 --- a/android-sdk/modules.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: modules -title: Modules overview -description: Choose between Core and Compose based on your app architecture. ---- - -Tolgee Android SDK is split into modules so you only add what you need. - -## When to use which module - -- **Core** - - Use with traditional Android Views or any non-Compose UI. - - Provides content delivery (CDN), key lookup, formatting (Sprintf/ICU), caching. - - Start here if you don't use Jetpack Compose. - -- **Compose** - - Use with Jetpack Compose or Compose Multiplatform. - - Adds localized composables and helpers (e.g., `stringResource`, `pluralStringResource`). - - Requires `core` transitively. - -> NOTE: -> The Gradle compiler plugin is not released yet and is not part of the current installation options. - -## Installation snippets - -Using a Version Catalog is recommended. - -```toml -# gradle/libs.versions.toml -[libraries] -tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" } -``` - -```kotlin -// build.gradle.kts (Core) -dependencies { - implementation(libs.tolgee) -} -``` - -For Compose, use the `compose` artifact instead of `core`: - -```toml -# gradle/libs.versions.toml -[libraries] -tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" } -``` - -```kotlin -// build.gradle.kts (Compose) -dependencies { - implementation(libs.tolgee) -} -``` - - -## Demos - -- Views: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/HEAD/demo/exampleandroid -- Compose: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/HEAD/demo/examplejetpack -- Compose Multiplatform: https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/HEAD/demo/multiplatform-compose - -## Next steps - -- Ship confidently: [Production guide](./production.mdx) diff --git a/android-sdk/overview.mdx b/android-sdk/overview.mdx new file mode 100644 index 000000000..7c807e6d8 --- /dev/null +++ b/android-sdk/overview.mdx @@ -0,0 +1,49 @@ +--- +id: overview +title: Overview +slug: / +description: Overview of Tolgee Android SDK with Over‑the‑Air (OTA) localization updates for Android and Compose Multiplatform. +--- + +import SystemCard from '@site/src/component/SystemCard'; +import FeatureGrid from '@site/src/component/FeatureGrid'; +import { ScreenshotWrapper } from '../platform/shared/_ScreenshotWrapper'; +import AndroidApiRequirement from '@site/src/component/AndroidApiRequirement'; + +# Tolgee Android SDK + +## Overview + +Tolgee Android SDK provides localization support for Kotlin-based projects, with a primary focus on Android applications. It enables **Over-the-Air (OTA)** translation updates, allowing you to deliver new or updated translations at runtime **without rebuilding or publishing a new version of your app**. + +Once integrated, the SDK handles fetching and applying translations dynamically, so developers no longer need to manually manage string resources, export localization files, or coordinate translation updates through app releases. + +The SDK integrates seamlessly with both **Android Views** and **Jetpack Compose**, supports reactive locale changes, and is built with **Kotlin Multiplatform** compatibility in mind. + +## Features + +### Over-the-Air (OTA) Content Delivery + +Update translations dynamically at runtime. Save a lot of time when releasing new or updated translations. No need to wait for them to be published via Google Play or App Store. + +### Multiple format support + +- **Android XML format** with [sprintf-style placeholders](/platform/formats/android_xml) (`%s`, `%d`, etc.) +- **ICU Message Format** with [Tolgee Universal ICU placeholders](/platform/translation_process/icu_message_format) (advanced formatting) + +### Compose integration + +Full integration with Jetpack Compose and Compose Multiplatform + +### Kotlin Multiplatform support + +Designed with multiplatform projects in mind. + +### Flexible hosting options + +Connect to [Tolgee Cloud](/platform/) or [self-hosted](/platform/self_hosting/getting_started) instances. + +## Next steps +- Install and configure the SDK: [Installation](./installation.mdx) +- Connect your app to the Tolgee Platform and manage translations collaboratively: [Platform docs](../platform/) +- Generate or manage static strings with CLI: [Tolgee CLI](/tolgee-cli) \ No newline at end of file diff --git a/android-sdk/production.mdx b/android-sdk/production.mdx deleted file mode 100644 index 2ec046ce4..000000000 --- a/android-sdk/production.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -id: production -title: Production guide -description: OTA updates, caching, formatting, and deployment tips for shipping to production. ---- - -This guide summarizes recommendations for using Tolgee Android SDK in production. - -## Over‑the‑air (OTA) updates & caching - -- **CDN**: Configure your CDN URL prefix and a stable path per project/environment. -- **Caching**: Use `TolgeeStorageProviderAndroid(context, BuildConfig.VERSION_CODE)` so cache invalidates on app updates. -- **Offline behavior**: SDK serves cached values when offline; provide static fallbacks where needed. - -```kotlin -Tolgee.init { - contentDelivery { - url = "https://cdn.tolg.ee/your-cdn-url-prefix" - storage = TolgeeStorageProviderAndroid(appContext, BuildConfig.VERSION_CODE) - } -} -``` - -## Formatting mode (Sprintf vs ICU) - -- **Sprintf**: Natural when your source data comes from Android XML (`%s`, `%d`, plurals). -- **ICU**: Use when your data uses Tolgee Universal ICU placeholders. - -```kotlin -Tolgee.init { - contentDelivery { - // Default is Sprintf for Android-style placeholders - format(Tolgee.Formatter.Sprintf) - // Or switch to ICU: - // format(Tolgee.Formatter.ICU) - } -} -``` - -See also: [Android XML format](/platform/formats/android_xml) · [Tolgee Universal ICU placeholders](/platform/translation_process/tolgee_universal_icu_placeholders) - -## Preloading & startup - -- Preload critical namespaces/locales on splash or application init. -- Defer non-critical content until after first frame to keep startup fast. -- Show fallback strings while loading. - -## Environments - -- Use separate CDN prefixes for dev/staging/prod. -- Verify cache busting between releases (via `BuildConfig.VERSION_CODE`). - -## Error handling - -- Log fetch failures and fall back to cache/static values. -- Consider retry/backoff for transient network errors. - -## Security & networking - -- Add only required domains in your `network_security.xml`. -- For self-hosting, ensure TLS and set correct domain(s). See [Self‑hosting](/platform/self_hosting/getting_started). - -## Testing - -- Provide test doubles for content delivery to return deterministic values. -- For UI tests, inject a test Tolgee instance with preloaded data. diff --git a/android-sdk/setup.mdx b/android-sdk/setup.mdx new file mode 100644 index 000000000..fe2e27690 --- /dev/null +++ b/android-sdk/setup.mdx @@ -0,0 +1,87 @@ +--- +id: setup +title: Setup +description: Learn how to initialize and configure Tolgee Android SDK in your application +--- + +# Setup + +After installing the Tolgee SDK, you need to initialize it in your application. This one-time setup process: + +- Configures the SDK to connect to your translation content delivery network (CDN) +- Sets up local caching for offline access and performance +- Establishes the global Tolgee instance that your entire app can access +- Enables over-the-air translation updates without releasing a new app version + +Once properly initialized, Tolgee will automatically handle translation fetching, caching, and updates throughout your application's lifecycle. + +## Initialization Configuration + +:::note Universal Setup +This initialization applies to **all Tolgee Android SDK variants** - Android Views (Core), Jetpack Compose, and Kotlin Multiplatform. +::: + +### Android + +Initialize Tolgee in your `Application` class: + +```kotlin +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + Tolgee.init { + contentDelivery { + url = "https://cdn.tolg.ee/your-cdn-url-prefix" // from Tolgee Platform → Content Delivery + storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update + } + } + } +} +``` + +Make sure that your app knows where to download translations + +**For your app to download translation files, you need to provide a CDN URL prefix specific to your project.** +This prefix points to the catalog that contains your app's translations. + +**To get your CDN URL prefix:** + +1. Open **Tolgee Platform → your Project → Developer settings → [Content Delivery](/platform/projects_and_organizations/content_delivery)** +2. Copy the full CDN URL prefix +3. You can use different prefixes per environment (dev/staging/prod) + +:::info +If you have a different integration setup (for example, using tolgee-cli and bundling JSON translation files in assets), the initialization may look different. +::: + +### Kotlin Multiplatform (Non-Android Targets) + +For non-Android targets in Kotlin Multiplatform projects, initialization is similar but requires a custom storage provider: + +```kotlin +fun initTolgee() { + Tolgee.init { + contentDelivery { + url = "https://cdn.tolg.ee/your-cdn-url-prefix" + // Create a custom storage provider for caching the latest translations from CDN if needed + } + } +} +``` + +:::note +You'll need to implement your own storage provider for non-Android platforms to enable caching of translations. +::: + +## Alternative Setup: Using Static Data + +If you prefer to bundle translations with your app or need offline-first capabilities, you can use [Tolgee CLI](/tolgee-cli/installation) to manage translations as static files. + + +:::tip +Using Tolgee CLI with static files is ideal for: +- Offline-first applications +- Apps with strict security requirements +- Development environments without internet access +- CI/CD pipelines that need deterministic builds +::: diff --git a/android-sdk/troubleshooting.mdx b/android-sdk/troubleshooting.mdx index fa9e0f819..93004c27c 100644 --- a/android-sdk/troubleshooting.mdx +++ b/android-sdk/troubleshooting.mdx @@ -4,60 +4,13 @@ title: Troubleshooting description: Troubleshooting Tolgee Android SDK --- -## Translations Not Loading +## Fast Checklist -- Verify the CDN URL prefix (copy the full Content Delivery URL from Tolgee Platform → Developer settings → Content Delivery). -- Ensure `Tolgee.init` runs early (e.g., in `Application.onCreate`). -- Configure storage for caching: `TolgeeStorageProviderAndroid(context, BuildConfig.VERSION_CODE)`. -- Load data before reading: - - Views: call `tolgee.preload(activity)` in `onStart`, or use `tolgee.tFlow` for reactive updates. - - Compose: use `stringResource`/`pluralStringResource` which handle updates automatically. -- Test connectivity to your CDN URL prefix: +### General Setup + +- **Check if Maven Central is in repositories** - `mavenCentral` in `settings.gradle.kts`. +- **Check if CDN URL is proper and accessible** - test connection locally: ```bash curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json" -``` - -Expect HTTP 200. For 403/404, re‑copy the prefix and check project permissions. - -### CDN/Network - -- If using Tolgee Cloud, verify your `network_security.xml` includes `tolgee.io` and `tolg.ee` domains and that the `AndroidManifest.xml` references it via `android:networkSecurityConfig`. -- If self-hosting, replace CDN URL with your domain and allow it in `network_security.xml`. -- Test connectivity to the CDN URL prefix in a browser/curl to ensure it returns JSON bundles. - -## Locale Issues - -- Verify that your project supports the locale code you're using -- Check that translations for the selected locale exist in your Tolgee project -- Use `tolgee.changeFlow` to monitor locale changes and update your UI accordingly - -## Android Integration Issues - -- Ensure that the `TolgeeStorageProviderAndroid` is properly initialized with the context and version code which changes with each app update -- Check that your Android resources are properly structured - Tolgee is using `resources.getResourceEntryName` to find key for the resource -- Activity context isn't wrapped: Make sure Activities override `attachBaseContext` and call `TolgeeContextWrapper.wrap(newBase)` so `getString` uses Tolgee. - -### Common error messages and fixes - -- java.net.UnknownServiceException: CLEARTEXT communication to `` not permitted - - Cause: Required domain(s) are using plain http and are not allowed in network security config. - - Fix: Add domains to res/xml/network_security.xml and reference it from AndroidManifest via android:networkSecurityConfig. - -- HTTP 403/404 when fetching from CDN prefix - - Cause: Incorrect CDN URL prefix. - - Fix: Copy the exact CDN URL prefix from Tolgee Platform, verify the environment, and test in a browser/curl. - - Note: If using namespaces, include the namespace in the URL prefix; The SDK does not support namespaces natively yet. - -## Version Mismatch - -- Make sure your app uses a consistent `tolgeeVersion` across `core` and `compose` artifacts. -- If you migrated formats, confirm formatter configuration matches your data (e.g., `Sprintf` vs `ICU`). - -## Useful links - -- Installation: [Installation](./installation.mdx) -- Usage (Views): [Usage](./usage.mdx) -- Jetpack Compose: [Installation](./jetpack/installation.mdx), [Usage](./jetpack/usage.mdx) -- CLI for static strings: [Tolgee CLI](/tolgee-cli/installation) - +``` \ No newline at end of file diff --git a/android-sdk/usage.mdx b/android-sdk/usage.mdx index 1641583cc..230210ecf 100644 --- a/android-sdk/usage.mdx +++ b/android-sdk/usage.mdx @@ -1,182 +1,251 @@ --- id: usage -title: Usage -description: How to use Tolgee Android SDK in your Android application +title: Usage +description: How to use Tolgee Android SDK with traditional Android Views --- -## Quickstart +# Usage -1) Ensure you have completed Installation and Initialization in your Application class. See: [Installation](./installation.mdx) +This guide shows you how to use the Tolgee Android SDK with traditional Android Views. For Jetpack Compose usage, see [Jetpack Compose Usage](./jetpack/usage.mdx). -2) Wrap your Activity context so Android resource lookups (getString, etc.) use Tolgee: +## Prerequisites + +Ensure you have completed the quickstart guide and initialized Tolgee in your Application class. See: [Installation](./installation.mdx) + +## Get The Global Tolgee Instance + +After you have initialized Tolgee in your app, following the quickstart guide. +Set up a singleton Tolgee global instance, this allows you to use Tolgee. ```kotlin -class MyActivity : Activity() { - override fun attachBaseContext(newBase: Context?) { - super.attachBaseContext(TolgeeContextWrapper.wrap(newBase)) - } -} +val tolgee = Tolgee.instance ``` -> TIP: -> If you use AppCompatActivity, the same approach applies. Wrap the base context in `attachBaseContext`. +From now on you can: + +- get translations: `tolgee.t("key")`, `tolgee.tFlow("key")`, +- change locales: `tolgee.setLocale("xx")`, +- listen for changes: `tolgee.changeFlow`; + +## Getting Translations + +In this section, the translation types are demonstrated. Here you can see a quick overview: -3) (If preferred) Recreate the Activity when translations change: +:::note +If you are unsure of which translation type to choose, notice a “Use for...” section under every explanation. +::: + +### One time translations: ```kotlin -class MyActivity : Activity() { - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - val tolgee = Tolgee.instance - lifecycleScope.launch { - tolgee.changeFlow.collect { - // Locale or translations changed - recreate() - } - } - } -} +val text: String? = tolgee.t("key") ``` -or using good old listener: +Returns null if translations are not yet loaded (e.g., SDK hasn't downloaded data). +Returns a key when translations are loaded. + +**Use for simple/static text** (e. g., error messages, titles). + +### Translation with parameters: ```kotlin -class MyActivity : Activity(), Tolgee.ChangeListener { - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - tolgee.addChangeListener(this) - } +val textWithParams: String? = tolgee.t("key_with_param", mapOf("param" to "value")) +``` - override fun onDestroy() { - super.onDestroy() - tolgee.removeChangeListener(this) - } +**_Use for translation with dynamic values._** Add data that changes during the app's runtime (e.g., dates, numbers, usernames). - override fun onTranslationsChanged() { - recreate() - } +#### a) Preload translations for the current locale from Activity + +```kotlin +override fun onStart() { + super.onStart() + tolgee.preload(this) } ``` -4) Fetch and display a translation with a safe fallback to your Android resources: +Improves perceived performance - ensures keys are ready sooner for the current locale. + +**Use for UI’s where the translations are critical (e.g., login, onboarding).** + +:::tip +Create a global corutine by calling `tolgee.preload()` function with mentioned above one-time translations and translations with parameters. +::: + +#### b) Get a translation with fallback to Android resources + +**Fallbacks provide a safety net** in case of any problems with loading the translation or pulling from Android resources. + +One time translation with fallbacks: ```kotlin -val tolgee = Tolgee.instance val text = tolgee.t(context, R.string.string_key) -textView.text = text ``` -## With Parameters - -Provide arguments for placeholders in your strings: +Translation with parameters & fallbacks: ```kotlin val textWithParams = tolgee.t(context, R.string.string_with_params, "param1", "param2") -textView.text = textWithParams ``` +:::warning +To use parameters with Android fallbacks and ensure that translations from CDN can be interpreted, follow ICU order. +::: -> TIP: -> Parameters map to Android-style placeholders in order (e.g., %1$s, %2$d). +#### c) Semi-dynamic updates for classic Views -## Plurals +To receive **fresh translations without needing to publish new app versions** follow these steps: -Handle Android plurals via resources: +1. **Wrap your Activity context** so Android resource lookups use Tolgee: ```kotlin -val itemsText = tolgee.tPlural(context, R.plurals.items_count, count, count) -textView.text = itemsText +class MyActivity : Activity() { + override fun attachBaseContext(newBase: Context?) { + super.attachBaseContext(TolgeeContextWrapper.wrap(newBase)) + } +} ``` -> NOTE: -> - The second `count` argument is the formatting parameter used inside the string (typical Android pattern when you want to show the number). -> - Tolgee resolves the key from your Android resource ID using `resources.getResourceEntryName`. Ensure the keys exist in Tolgee Platform as well. -> - Limitation: Only one plural per string is supported (Android plural resources). Nested or multiple plurals in a single string are not supported. - -## Language Switching +The `TolgeeContextWrapper` intercepts all calls to `getString()`, `getQuantityString()`, and other resource methods, replacing them with Tolgee translations when available. This allows your existing Android code to use Tolgee translations without any changes to the code that calls `getString()`. -Set locale: +2. **Trigger a UI refresh** when locale or translations change: ```kotlin -tolgee.setLocale("en") +lifecycleScope.launch { + tolgee.changeFlow.collect { + recreate() // reloads the Activity, Views get fresh translations + } +} ``` -Get current locale: +Combining these two approaches gives you **semi-dynamic behavior, translations update after an Activity reload, not instantly**. +This setup works with both one-time translations and translations with parameters. + +### Get dynamic (reactive) translations. ```kotlin -val locale = tolgee.getLocale() +val textFlow: Flow = tolgee.tFlow("key") +textFlow.collect { text -> + // Use the text (e.g., update UI) +} ``` -Listen for changes: +**Use for reactive UI.** Translations update **immediately and automatically** whenever the language or CDN data changes. + +#### Dynamic translation with fallback to Android resources ```kotlin -tolgee.changeFlow.collect { - // Locale or available translations changed, update UI if needed -} +val textFlow = tolgee.tFlow(context, R.string.string_key) ``` -## Advanced Configuration +:::note +In Compose, use `collectAsState()` function for a more idiomatic integration. +::: ### Formatter Configuration -Configure formatters for parsing translations from CDN: +**Choose how placeholders are parsed and rendered.** +Use when you have translations with placeholders, SDK must know how to exchange the placeholders for wanted values. +**Example**: "`Hello %s`" or"`You have {count} items`" + +See also: [Android XML format](/platform/formats/android_xml) · [Tolgee Universal ICU placeholders](/platform/translation_process/tolgee_universal_icu_placeholders) + +**1. Sprintf** ```kotlin Tolgee.init { contentDelivery { url = "https://cdn.tolg.ee/your-cdn-url-prefix" - format(Tolgee.Formatter.Sprintf) // Android SDK formatting (default) - // format(Tolgee.Formatter.ICU) // Tolgee Native Flat JSON formatting + format(Tolgee.Formatter.Sprintf) } } ``` -### Preloading Translations +**Use for easy scenarios**, when you are using formatters, like `%s, %d, %1$s`. -Preload translations for the current locale from Activity: +:::warning +**This parameter type won't work with fallbacks to Android Resources** - it's not functional for apps with any offline activity. +::: + +**2. ICU** ```kotlin -override fun onStart() { - super.onStart() - tolgee.preload(this) +Tolgee.init { + contentDelivery { + url = "https://cdn.tolg.ee/your-cdn-url-prefix" + format(Tolgee.Formatter.ICU) + } } ``` -### Reactive lookups with tFlow +**Use for more advanced translations and ICU features**, when you need nested formats or formatters, + like e.g. few, may, female, and complex lingual principles. -You can also use `tFlow` to reactively update a specific string when translations change: +## Plurals + +Plurals ensure your app displays grammatically correct text based on the count, so users always see localized phrases. + +:::info +Tolgee advantage: keeps plural rules and translations in sync across languages, without you needing to hardcode them. +::: + +**Handle Android plurals via resources:** ```kotlin -lifecycleScope.launch { - tolgee.tFlow(context, R.string.string_key).collect { text -> - textView.text = text - } -} +val itemsText = tolgee.tPlural(context, R.plurals.items_count, count, count) +textView.text = itemsText ``` -> TIP: -> `tFlow` updates when locale or available translations change. This can be used for live updates without the need for full activity recreate. +**Use for lists, counters, notifications** — any situation where the grammar changes with quantity. + +See also: [Android XML format](/platform/formats/android_xml) · [Tolgee Universal ICU placeholders](/platform/translation_process/tolgee_universal_icu_placeholders) -## Obtaining a Tolgee instance +## Locale Management -Most apps use the singleton: +This section addresses deciding and controlling what **language and region** your app uses. + +### 1. Set the locale manually. ```kotlin -val tolgee = Tolgee.instance +tolgee.setLocale("en") +``` + +**Use when your app lets users pick a locale.** + +:::tip +Combine this with `recreate()` after language changes. This reloads your Activity and ensures Views show updated translations. +::: + +### 2. Get the current locale + +```kotlin +val locale = tolgee.getLocale() ``` -For DI or testing, you can hold a reference you created during initialization and pass it around explicitly. +**Use for checking what locale is working currently.** +Handy for displaying the current locale, debugging, or syncing with app/system settings. + +### 3. Listen for locale/translation changes + +```kotlin +lifecycleScope.launch { + tolgee.changeFlow.collect { + // locale or available translations changed + } +} +``` + +**Use for building dynamically updated UI.** +Enables you to create UI that stays in sync with locale changes and new translations. + -## Reactive UI updates -If your UI should react to translation/locale changes, subscribe to `changeFlow` and update state accordingly. See Compose examples in [Jetpack Compose Usage](./jetpack/usage.mdx). +## Example Projects -## Best practices +For a complete example of how to use the Tolgee Core module with Android Views, check out the demo project: -- **Preload** translations in `onStart` for Activities or when a Fragment becomes visible. -- **Avoid blocking calls** on the main thread; use flows for reactivity. -- **Keep keys in sync** between Android resources and Tolgee Platform. +**[Example Android](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/exampleandroid)** - Traditional Android Views example -## Next steps +## Next Steps -- Using Compose? Continue with [Jetpack Compose Usage](./jetpack/usage.mdx) -- Problems? See [Troubleshooting](./troubleshooting.mdx) +- **Using Jetpack Compose?** See [Jetpack Compose Usage](./jetpack/usage.mdx) +- **Having issues?** Check [Troubleshooting](./troubleshooting.mdx) +- **Need example apps?** See [Example Apps](./example-apps.mdx) diff --git a/platform/faq.mdx b/platform/faq.mdx index 520b5bb54..f6f6a8897 100644 --- a/platform/faq.mdx +++ b/platform/faq.mdx @@ -34,7 +34,6 @@ Yes. Tolgee provides a native [Android SDK](/android-sdk) that integrates with y - Get started: [Installation](/android-sdk/installation) - Use translations: [Usage](/android-sdk/usage) -- Compose UI: [Jetpack Compose](/android-sdk/jetpack/installation) - File format details: [Android Resources XML](/platform/formats/android_xml) Glass -> eyeglasses or glass for a drink? diff --git a/platform/formats/android_xml.mdx b/platform/formats/android_xml.mdx index 523a8e9ff..f86770c11 100644 --- a/platform/formats/android_xml.mdx +++ b/platform/formats/android_xml.mdx @@ -86,7 +86,7 @@ Tolgee.init { See also: -- Android SDK: [Installation](/android-sdk/installation) · [Usage](/android-sdk/usage) · [Jetpack Compose](/android-sdk/jetpack/installation) +- [Android SDK](/android-sdk) ## Array support When importing data to Tolgee from the Android XML files, the array elements are converted into flat keys with diff --git a/platform/getting_started/about_tolgee.mdx b/platform/getting_started/about_tolgee.mdx index 62c666652..83af9bf42 100644 --- a/platform/getting_started/about_tolgee.mdx +++ b/platform/getting_started/about_tolgee.mdx @@ -29,6 +29,8 @@ If you want to try Tolgee, you can [sign up](https://app.tolgee.io/sign_up) for ## Other Tolgee Docs - [JavaScript SDK](/js-sdk) +- [Android SDK](/android-sdk) +- [iOS SDK](/ios-sdk) - [Tolgee CLI](/tolgee-cli) - [REST API](/api) diff --git a/platform/getting_started/translation_content.mdx b/platform/getting_started/translation_content.mdx index e9d9ce877..26aef9158 100644 --- a/platform/getting_started/translation_content.mdx +++ b/platform/getting_started/translation_content.mdx @@ -40,6 +40,5 @@ Tolgee also provides an [Android SDK](/android-sdk) for native Android apps, inc - Install and initialize the SDK: [Installation](/android-sdk/installation) - Use translations in Views and handle plurals/parameters: [Usage](/android-sdk/usage) -- Use localized composables: [Jetpack Compose](/android-sdk/jetpack/installation) -In production, configure content delivery (CDN) using the Android [Installation](/android-sdk/installation) and [Production guide](/android-sdk/production), and preload data as needed. +In production, configure content delivery (CDN) using the Android, and preload data as needed. diff --git a/sidebarAndroidSdk.js b/sidebarAndroidSdk.js index 019b2135b..bc91ebeb2 100644 --- a/sidebarAndroidSdk.js +++ b/sidebarAndroidSdk.js @@ -1,18 +1,17 @@ module.exports = { someSidebar: [ - 'about', - { - type: 'category', - label: 'Get started', - items: ['installation', 'modules'], - }, + 'overview', + 'installation', + 'setup', 'usage', { type: 'category', label: 'Jetpack Compose', - items: ['jetpack/installation', 'jetpack/usage', 'jetpack/troubleshooting'], + items: [ + 'jetpack/usage', + ], }, - 'production', + 'example-apps', 'troubleshooting', ], -}; \ No newline at end of file +}; diff --git a/src/component/AndroidApiRequirement.tsx b/src/component/AndroidApiRequirement.tsx new file mode 100644 index 000000000..aff85b728 --- /dev/null +++ b/src/component/AndroidApiRequirement.tsx @@ -0,0 +1,38 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; +import Heading from '@theme/Heading'; + +export default function AndroidApiRequirement() { + return ( +
+
+
+ Android +
+ + Android API Level + +

+ Minimum{' '} + + API Level 21+ + {' '} + (Android 5.0 and above) +

+
+
+
+
+ ); +} diff --git a/src/component/FeatureGrid.tsx b/src/component/FeatureGrid.tsx new file mode 100644 index 000000000..3a863172c --- /dev/null +++ b/src/component/FeatureGrid.tsx @@ -0,0 +1,70 @@ +import React from 'react'; +import Heading from '@theme/Heading'; + +interface Feature { + emoji: string; + title: string; + description: string; + colorTheme: 'blue' | 'green' | 'purple' | 'orange'; +} + +interface FeatureGridProps { + features: Feature[]; +} + +const colorClasses = { + blue: { + bg: 'bg-gradient-to-br from-blue-50 to-blue-100 dark:from-blue-900/20 dark:to-blue-800/20', + border: 'border-gray-200 dark:border-gray-700', + title: 'text-blue-800 dark:text-blue-200', + text: 'text-blue-700 dark:text-blue-300', + }, + green: { + bg: 'bg-gradient-to-br from-green-50 to-green-100 dark:from-green-900/20 dark:to-green-800/20', + border: 'border-gray-200 dark:border-gray-700', + title: 'text-green-800 dark:text-green-200', + text: 'text-green-700 dark:text-green-300', + }, + purple: { + bg: 'bg-gradient-to-br from-purple-50 to-purple-100 dark:from-purple-900/20 dark:to-purple-800/20', + border: 'border-gray-200 dark:border-gray-700', + title: 'text-purple-800 dark:text-purple-200', + text: 'text-purple-700 dark:text-purple-300', + }, + orange: { + bg: 'bg-gradient-to-br from-orange-50 to-orange-100 dark:from-orange-900/20 dark:to-orange-800/20', + border: 'border-gray-200 dark:border-gray-700', + title: 'text-orange-800 dark:text-orange-200', + text: 'text-orange-700 dark:text-orange-300', + }, +}; + +export default function FeatureGrid({ features }: FeatureGridProps) { + return ( +
+ {features.map((feature, index) => { + const colors = colorClasses[feature.colorTheme]; + return ( +
+
+ {feature.emoji} + + {feature.title} + +
+
+
+ ); + })} +
+ ); +} diff --git a/src/component/SystemCard.tsx b/src/component/SystemCard.tsx new file mode 100644 index 000000000..f84d60812 --- /dev/null +++ b/src/component/SystemCard.tsx @@ -0,0 +1,60 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; +import Heading from '@theme/Heading'; + +interface SystemCardProps { + title: string; + emoji: string; + description: string; + links: Array<{ + href: string; + label: string; + color: 'blue' | 'green' | 'orange' | 'purple' | 'cyan'; + }>; +} + +const colorClasses = { + blue: 'bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-200 hover:bg-blue-200 dark:hover:bg-blue-800', + green: + 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200 hover:bg-green-200 dark:hover:bg-green-800', + orange: + 'bg-orange-100 dark:bg-orange-900 text-orange-800 dark:text-orange-200 hover:bg-orange-200 dark:hover:bg-orange-800', + purple: + 'bg-purple-100 dark:bg-purple-900 text-purple-800 dark:text-purple-200 hover:bg-purple-200 dark:hover:bg-purple-800', + cyan: 'bg-cyan-100 dark:bg-cyan-900 text-cyan-800 dark:text-cyan-200 hover:bg-cyan-200 dark:hover:bg-cyan-800', +}; + +export default function SystemCard({ + title, + emoji, + description, + links, +}: SystemCardProps) { + return ( +
+ + {emoji} {title} + +

+

+ {links.map((link, index) => ( + + {link.label} + + ))} +
+
+ ); +} diff --git a/src/component/docsIndex/DocsTile.tsx b/src/component/docsIndex/DocsTile.tsx index d9d8407d3..321f66b3a 100644 --- a/src/component/docsIndex/DocsTile.tsx +++ b/src/component/docsIndex/DocsTile.tsx @@ -12,7 +12,7 @@ type Props = { export const DocsTile = ({ title, text, link, linkText }: Props) => { return (
diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 97b854f1b..834524955 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -38,8 +38,8 @@ function Home() { Tolgee is a localization platform that streamlines translations for web, mobile, and desktop apps. With tools like the SDK, CLI, and REST API, it simplifies in-context translation and string - management for efficient localization. Explore the docs to get - started! + management for efficient internationalization. Explore the docs + to get started!

+ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/static/img/docs/sdk/jetpack-compose.png b/static/img/docs/sdk/jetpack-compose.png new file mode 100644 index 000000000..1db89ff70 Binary files /dev/null and b/static/img/docs/sdk/jetpack-compose.png differ diff --git a/tailwind.config.js b/tailwind.config.js index 74c010448..e42e4b369 100644 --- a/tailwind.config.js +++ b/tailwind.config.js @@ -1,6 +1,6 @@ /** @type {import('tailwindcss').Config} */ module.exports = { - content: ['./src/**/*.{js,jsx,ts,tsx}'], + content: ['./src/**/*.{js,jsx,ts,tsx}', './**/*.{md,mdx}'], darkMode: 'class', theme: { extend: {