Skip to content

Commit 7e135e3

Browse files
Anty0Anty0
committed
feat: update README + rollback version + small fixes
1 parent b64bf8b commit 7e135e3

10 files changed

Lines changed: 654 additions & 95 deletions

File tree

‎README.md‎

Lines changed: 100 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,144 @@
1-
# Kotlin Multiplatform and Android package for Tolgee
1+
# Tolgee Mobile Kotlin SDK (Alpha)
22

3-
🚨🚨🚨This package is currently under heavy development and will be released under alpha versions until stable and properly tested by pilot users.🚨🚨🚨
3+
🚨🚨🚨This package is still under development and the API is not yet stable.
4+
Feel free to use it, but there might be API breakage between releases.🚨🚨🚨
45

5-
[![Tolgee](https://img.shields.io/badge/Tolgee-f06695?style=for-the-badge)](https://tolgee.io/) ![Compose Multiplatform](https://img.shields.io/badge/Compose%20Multiplatform-Supported-green?style=for-the-badge) ![Jetpack Compose](https://img.shields.io/badge/Jetpack%20Compose-Supported-green?style=for-the-badge)
6+
[![Tolgee](https://img.shields.io/badge/Tolgee-f06695)](https://tolgee.io/)
7+
![Android](https://img.shields.io/badge/Android-Supported-green?logo=android)
8+
![Jetpack Compose](https://img.shields.io/badge/Jetpack%20Compose-Supported-green?logo=jetpackcompose)
9+
![Compose Multiplatform](https://img.shields.io/badge/Compose%20Multiplatform-Supported-green?logo=kotlin)
10+
![language](https://img.shields.io/github/languages/top/tolgee/tolgee-mobile-kotlin-sdk)
11+
[![github release](https://img.shields.io/github/v/release/tolgee/tolgee-mobile-kotlin-sdk?label=GitHub%20Release)](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/releases/latest)
12+
[![licence](https://img.shields.io/badge/license-Apache%202%20-blue)](https://github.com/tolgee/tolgee-mobile-kotlin-sdk/blob/master/LICENSE)
13+
[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-mobile-kotlin-sdk?style=social&label=Tolgee%20Mobile%20Kotlin%20SDK)](https://github.com/tolgee/tolgee-mobile-kotlin-sdk)
14+
[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-platform?style=social&label=Tolgee%20Platform)](https://github.com/tolgee/tolgee-platform)
15+
[![Github discussions](https://img.shields.io/github/discussions/tolgee/tolgee-platform)](https://github.com/tolgee/tolgee-platform/discussions)
16+
[![Dev.to](https://img.shields.io/badge/Dev.to-tolgee_i18n?logo=devdotto&logoColor=white)](https://dev.to/tolgee_i18n)
17+
[![Read the Docs](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=fff)](https://docs.tolgee.io/)
18+
[![Slack](https://img.shields.io/badge/Slack-4A154B?logo=slack&logoColor=fff)](https://tolg.ee/slack)
19+
[![YouTube](https://img.shields.io/badge/YouTube-%23FF0000.svg?logo=YouTube&logoColor=white)](https://www.youtube.com/@tolgee)
20+
[![LinkedIn](https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff)](https://www.linkedin.com/company/tolgee/)
21+
[![X](https://img.shields.io/badge/X-%23000000.svg?logo=X&logoColor=white)](https://x.com/Tolgee_i18n)
622

7-
A flexible Gradle plugin and runtime library for integrating [Tolgee translations](https://tolgee.io) into **Kotlin Multiplatform** and **Compose** projects.
23+
## What is Tolgee?
824

9-
## Gradle plugin
25+
[Tolgee](https://tolgee.io/) is a powerful localization platform that simplifies the translation process for your applications.
26+
This SDK provides integration for Kotlin-based projects, with a primary focus on Android.
1027

11-
Comes with a convenient task to pull your latest translations directly into your resources folder.
28+
Currently, Android is fully supported, but any Kotlin-based codebase can in theory use this library.
1229

13-
### Setup
30+
## Features
1431

15-
Using Version Catalog is highly recommended to keep your versions aligned.
16-
17-
```toml
18-
[plugins]
19-
tolgee = { id = "dev.datlag.tolgee", version.ref = "tolgee" }
20-
```
32+
- **Over-the-air updates**: Update your translations without releasing a new app version
33+
- **Multiple format support**:
34+
- Sprintf (Android SDK) formatting
35+
- ICU (Tolgee Native Flat JSON) formatting
36+
- **Compose integration**: Full integration with Jetpack Compose and Compose Multiplatform
37+
- **Compiler plugin**: Automatically transform existing code to use Tolgee without manual changes
38+
- **Kotlin Multiplatform**: Designed with multiplatform support in mind
2139

22-
**Configuration**
23-
24-
You can change the plugin behavior to your needs:
25-
26-
```kotlin
27-
tolgee {
28-
// REQUIRED
29-
apiKey.set("<YOUR TOLGEE APIKEY WITH TRANSLATION READ ACCESS>") // or use the 'tolgee.apikey=' property instead
30-
31-
// more options
32-
pull { ... }
33-
push { ... }
34-
35-
// change compile time behavior
36-
compilerPlugin {
37-
android {
38-
// Replaces Context.getString occurrences with Context.getStringT
39-
replaceGetString.set(false) // default true
40-
}
41-
}
42-
}
43-
```
40+
## Modules
4441

45-
### Usage
42+
The SDK is split into multiple modules, each serving a specific purpose:
4643

47-
Pull translations from Tolgee using the `pullTranslation` Gradle task.
48-
Push local translations to Tolgee using the `pushTranslation` Gradle task.
44+
- **[Core](./core/README.md)**: Base library for fetching translations from CDN and querying them
45+
- **[Compose](./compose/README.md)**: Extension for using the library with Jetpack Compose or Compose Multiplatform
46+
- **[Gradle Plugin](./gradle-plugin/README.md)**: Gradle plugin for integrating and configuring the compiler plugin
4947

50-
## Core
48+
## Which Module Should I Use?
5149

52-
This Kotlin Multiplatform library provides runtime support for Tolgee translations in your app.
53-
No longer creating a new release just to update your strings.
50+
- If you are using **traditional Android Views**, use the [Core](./core/README.md) module
51+
- If you are using **Jetpack Compose** or **Compose Multiplatform**, use the [Compose](./compose/README.md) module
52+
- If you want to **automatically transform existing code** to use Tolgee, add the [Gradle Plugin](./gradle-plugin/README.md)
5453

55-
### Setup
54+
## Installation
5655

5756
Using Version Catalog is highly recommended to keep your versions aligned.
5857

58+
### Core Module (Traditional Android)
59+
5960
```toml
61+
# gradle/libs.versions.toml
6062
[libraries]
61-
tolgee = { group = "dev.datlag.tolgee", name = "core", version.ref = "tolgee" }
63+
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" }
6264
```
6365

64-
### Usage
65-
66-
Simply create a `Tolgee` singleton or multiple instances, using an API Key and/or a content delivery url.
66+
```kotlin
67+
// build.gradle.kts
68+
dependencies {
69+
implementation(libs.tolgee)
70+
}
71+
```
6772

68-
#### Content Delivery
73+
### Compose Module (Jetpack Compose or Compose Multiplatform)
6974

70-
Content Delivery supports JSON only and can be used with any formatting option.
75+
```toml
76+
# gradle/libs.versions.toml
77+
[libraries]
78+
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" }
79+
```
7180

7281
```kotlin
73-
/** Thread safe: Retrieve the current singleton or create one. */
74-
val tolgee = Tolgee.instanceOrInit {
75-
apiKey = "<API KEY>"
76-
contentDelivery("<ContentDelivery URL>") {
77-
format(Tolgee.Formatter.ICU) // default formatting
78-
format(Tolgee.Formatter.Sprintf) // for sprintf or Java.format formatting
79-
}
82+
// build.gradle.kts
83+
dependencies {
84+
implementation(libs.tolgee)
8085
}
86+
```
8187

82-
/** Updates the text automatically when loaded from API or locale changed. */
83-
val updatingText: Flow<String> = tolgee.translation("key")
88+
### Gradle Plugin (Compiler Plugin)
8489

85-
/** Returns the text that's currently loaded from API. */
86-
/** Requires `tolgee.preload` or `tolgee.translation` call else always null. */
87-
val currentText: String? = tolgee.instant("key")
90+
```toml
91+
# gradle/libs.versions.toml
92+
[plugins]
93+
tolgee = { id = "io.tolgee.mobile-kotlin-sdk", version.ref = "tolgee" }
8894
```
8995

90-
## Compose
96+
```kotlin
97+
// build.gradle.kts
98+
plugins {
99+
alias(libs.plugins.tolgee)
100+
}
101+
```
91102

92-
### Setup
103+
## Basic Usage
93104

94-
Using Version Catalog is highly recommended to keep your versions aligned.
105+
For detailed usage instructions, please refer to the module-specific documentation:
95106

96-
```toml
97-
[libraries]
98-
tolgee = { group = "dev.datlag.tolgee", name = "compose", version.ref = "tolgee" }
99-
```
107+
- [Core Module Documentation](./core/README.md)—For traditional Android and base functionality
108+
- [Compose Module Documentation](./compose/README.md)—For Jetpack Compose and Compose Multiplatform
109+
- [Gradle Plugin Documentation](./gradle-plugin/README.md)—For compiler plugin configuration
100110

101-
### Usage
111+
### Quick Start
102112

103-
```
104-
@Composable
105-
fun SimpleText() {
106-
Text(text = stringResource(tolgee, Res.string.about))
107-
}
113+
Here's a quick example of initializing Tolgee in an Android application:
108114

109-
@Composable
110-
fun ArgsSupported(vararg args: Any) {
111-
Text(text = stringResource(tolgee, Res.string.about, *args))
115+
```kotlin
116+
class MyApplication : Application() {
117+
override fun onCreate() {
118+
super.onCreate()
119+
120+
Tolgee.init {
121+
contentDelivery {
122+
url = "https://cdn.tolg.ee/your-cdn-url-prefix"
123+
storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE)
124+
}
125+
}
126+
}
112127
}
113128
```
114129

115-
#### Jetpack Compose?
130+
## Example Projects
116131

117-
What if you are using Jetpack Compose (Android only) or some explicit strings in your android source?
118-
No problem! This is handled as well.
132+
For complete examples of how to use the Tolgee SDK, check out the demo projects:
119133

120-
```kotlin
121-
@Composable
122-
fun AndroidOnly() {
123-
Text(text = i18n.stringResource(R.string.android_string))
124-
}
134+
- [Example Android](./demo/exampleandroid)—Traditional Android Views example
135+
- [Example Jetpack](./demo/examplejetpack)—Jetpack Compose example
136+
- [Multiplatform Compose](./demo/multiplatform-compose)—Compose Multiplatform example
125137

126-
@Composable
127-
fun AndroidWithArgs(vararg args: Any) {
128-
Text(text = i18n.stringResource(R.string.android_string, *args))
129-
}
130-
```
138+
## Contributing
131139

132-
### This is a non-profit project!
140+
Contributions are welcome! Please feel free to submit a Pull Request.
133141

134-
Sponsoring to this project means sponsoring to all my projects!
135-
So the further text is not to be attributed to this project, but to all my apps and libraries.
142+
## License
136143

137-
Supporting this project helps to keep it up-to-date. You can donate if you want or contribute to the project as well.
138-
This shows that the library is used by people, and it's worth to maintain.
144+
This project is licensed under the Apache License 2.0—see the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)