lyricist - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #ai #llm #go #golang #deep-learning #nodejs #awesome #cli #kubernetes #pytorch #ios #openai

lyricist

(★ 812)

🌎 The missing I18N/L10N (internationalization/localization) multiplatform library for Compose Multiplatform!

파일 탐색기

최종 버전 다운로드 (.zip)

- - release.yaml
- ci-gradle.properties
- FUNDING.yml
- .gitignore
- build.gradle.kts
- settings.gradle.kts
- - gradle-wrapper.jar
  - gradle-wrapper.properties
- libs.versions.toml
- yarn.lock
- .gitignore
- build.gradle.kts
- consumer-rules.pro
- gradle.properties
- .gitignore
- build.gradle.kts
- gradle.properties
- .gitignore
- build.gradle
- gradle.properties
- .gitignore
- build.gradle
- gradle.properties
- .gitignore
- build.gradle
- .gitignore
- build.gradle
- .gitignore
- build.gradle.kts
- README.md
- - ContentView.swift
  - iOSApp.swift
- .gitignore
- project.yml
- README.md
- .gitignore
- build.gradle
.editorconfig
.gitattributes
.gitignore
android-module.gradle
build.gradle
gradle.properties
gradlew
gradlew.bat
kotlin-module.gradle
LICENSE.md
README.md
settings.gradle.kts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/adrielcafe/lyricist

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd lyricist

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Gradle (Java/Kotlin)

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
JDK (Java) Java/Kotlin 프로젝트를 빌드/실행하려면 필요합니다.
Gradle 레포에 포함된 gradlew(Gradle Wrapper)를 쓰면 Gradle을 따로 설치할 필요가 없습니다.

// In your android module gradle file

Gradle로 빌드를 진행합니다.

tasks.withType<org.jetbrains.kotlin.gradle.dsl.KotlinCompile<*>>().all {

Gradle로 빌드를 진행합니다.

✅ BUILD SUCCESSFUL 메시지가 뜨면 성공입니다. build/ 폴더에 결과물이 생성됩니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Maven metadata URL](https://img.shields.io/maven-metadata/v?color=blue&metadataUrl=https://s01.oss.sonatype.org/service/local/repo_groups/public/content/cafe/adriel/lyricist/lyricist/maven-metadata.xml&style=for-the-badge)](https://central.sonatype.com/search?q=g%3Acafe.adriel.lyricist)
[![Android API](https://img.shields.io/badge/api-21%2B-brightgreen.svg?style=for-the-badge)](https://android-arsenal.com/api?level=21)
[![kotlin](https://img.shields.io/github/languages/top/adrielcafe/lyricist.svg?style=for-the-badge&color=blueviolet)](https://kotlinlang.org/)
[![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg?style=for-the-badge)](https://ktlint.github.io/)
[![License MIT](https://img.shields.io/github/license/adrielcafe/lyricist.svg?style=for-the-badge&color=orange)](https://opensource.org/licenses/MIT)

# Lyricist 🌎🌍🌏 
> The missing [I18N and L10N](https://en.wikipedia.org/wiki/Internationalization_and_localization) multiplatform library for [Jetpack Compose](https://developer.android.com/jetpack/compose)!

Jetpack Compose greatly improved the way we build UIs on Android, but not how we **interact with strings**. `stringResource()` works well, but doesn't benefit from the idiomatic Kotlin like Compose.

Lyricist tries to make working with strings as powerful as building UIs with Compose, *i.e.*, working with parameterized string is now typesafe, use of `when` expression to work with plurals with more flexibility, and even load/update the strings dynamically via an API!

#### Features
- [x] Multiplatform: Android, Desktop, iOS, Web (JsCanvas)
- [x] [Simple API](#usage) to handle locale changes and provide the current strings
- [x] [Multi module support](#multi-module-settings)
- [x] [Easy migration](#migrating-from-stringsxml) from `strings.xml`
- [x] [Extensible](#extending-lyricist): supports Compose Multiplatform out of the box but can be integrated on any UI Toolkit
- [x] Code generation with [KSP](https://github.com/google/ksp)

#### Limitations
* The XML processor doesn't handle `few` and `many` [plural values](https://developer.android.com/guide/topics/resources/string-resource#Plurals) (PRs are welcome)

#### Why _Lyricist_?
Inspired by [accompanist](https://github.com/google/accompanist#why-the-name) library: music composing is done by a composer, and since this library is about writing ~~lyrics~~ strings, the role of a [lyricist](https://en.wikipedia.org/wiki/Lyricist) felt like a good name.

## Usage
Take a look at the [sample app](https://github.com/adrielcafe/lyricist/tree/main/sample/src/main/java/cafe/adriel/lyricist/sample) and [sample-multi-module](https://github.com/adrielcafe/lyricist/tree/main/sample-multi-module/src/main/java/cafe/adriel/lyricist/sample/multimodule) for working examples.

Start by declaring your strings on a `data class`, `class` or `interface` (pick one). The strings can be anything (really, it's up to you): `Char`, `String`, `AnnotatedString`, `List<String>`, `Set<String>` or even lambdas!
```kotlin
data class Strings(
    val simple: String,
    val annotated: AnnotatedString,
    val parameter: (locale: String) -> String,
    val plural: (count: Int) -> String,
    val list: List<String>,
    val nestedStrings: NestedStrings(),
)

data class NestedStrings(
    ...
)
```

Next, create instances for each supported language and annotate with `@LyricistStrings`. The `languageTag` must be an [IETF BCP47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language tag ([docs](https://developer.android.com/guide/topics/resources/providing-resources#LocaleQualifier)). You must flag one of them as default.
```kotlin
@LyricistStrings(languageTag = Locales.EN, default = true)
val EnStrings = Strings(
    simple = "Hello Compose!",

annotated = buildAnnotatedString {
        withStyle(SpanStyle(color = Color.Red)) { 
            append("Hello ") 
        }
        withStyle(SpanStyle(fontWeight = FontWeight.Light)) { 
            append("Compose!") 
        }
    },

parameter = { locale ->
        "Current locale: $locale"
    },

plural = { count ->
        val value = when (count) {
            0 -> "no"
            1, 2 -> "a few"
            in 3..10 -> "a bunch of"
            else -> "a lot of"
        }
        "I have $value apples"
    },

list = listOf("Avocado", "Pineapple", "Plum")
)

@LyricistStrings(languageTag = Locales.PT)
val PtStrings = Strings(/* pt strings */)

@LyricistStrings(languageTag = Locales.ES)
val EsStrings = Strings(/* es strings */)

@LyricistStrings(languageTag = Locales.RU)
val RuStrings = Strings(/* ru strings */)
```

Lyricist will generate the `LocalStrings` property, a [CompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal) that provides the strings of the current locale. It will also generate `rememberStrings()` and `ProvideStrings()`, call them to make `LocalStrings` accessible down the tree.
```kotlin
val lyricist = rememberStrings()

ProvideStrings(lyricist) {
    // Content
}

// Or just 
ProvideStrings {
    // Content
}
```

Optionally, you can specify the current and default (used as fallback) languages.
```kotlin
val lyricist = rememberStrings(
    defaultLanguageTag = "es-US", // Default value is the one annotated with @LyricistStrings(default = true)
    currentLanguageTag = getCurrentLanguageTagFromLocalStorage(),
)
```

Now you can use `LocalStrings` to retrieve the current strings.
```kotlin
val strings = LocalStrings.current

Text(text = strings.simple)
// > Hello Compose!

Text(text = strings.annotated)
// > Hello Compose!

Text(text = strings.parameter(lyricist.languageTag))
// > Current locale: en

Text(text = strings.plural(1))
Text(text = strings.plural(5))
Text(text = strings.plural(20))
// > I have a few apples
// > I have a bunch of apples
// > I have a lot of apples

Text(text = strings.list.joinToString())
// > Avocado, Pineapple, Plum
```

Use the Lyricist instance provided by `rememberStrings()` to change the current locale. This will trigger a [recomposition](https://developer.android.com/jetpack/compose/mental-model#recomposition) that will update the entire content.
```kotlin
lyricist.languageTag = Locales.PT
```

**Important**

Lyricist uses the System locale as current language (on Compose it uses `Locale.current`). If your app has a mechanism to change the language in-app please set this value on `rememberStrings(currentLanguageTag = CURRENT_VALUE_HERE)`.

If you change the current language at runtime Lyricist won't persist the value on a local storage by itself, this should be done by you. You can save the current language tag on shared preferences, a local database or even through a remote API.

### Controlling the visibility
To control the visibility (`public` or `internal`) of the generated code, provide the following (optional) argument to KSP in the module's `build.gradle`.
```gradle
ksp {
    arg("lyricist.internalVisibility", "true")
}
```

### Generating a `strings` helper property
Instead of use `LocalStrings.current` to access your strings, you can simply call `strings`. Just provide the following (optional) argument to KSP in the module's `build.gradle`.
```gradle
ksp {
    arg("lyricist.generateStringsProperty", "true")
}
```
After a successfully build you can refactor your code as below. 
```kotlin
// Before
Text(text = LocalStrings.current.hello)

// After
Text(text = strings.hello)
```

## Multi module settings

If you are using Lyricist on a multi module project and the generated declarations (`LocalStrings`, `rememberStrings()`, `ProvideStrings()`) are too generic for you, provide the following (optional) arguments to KSP in the module's `build.gradle`.
```gradle
ksp {
    arg("lyricist.packageName", "com.my.app")
    arg("lyricist.moduleName", project.name)
}
```

Let's say you have a "dashboard" module, the generated declarations will be `LocalDashboardStrings`, `rememberDashboardStrings()` and `ProvideDashboardStrings()`.

## Migrating from `strings.xml`
So you liked Lyricist, but already have a project with thousands of strings spread over multiples files? I have good news for you: Lyricist can extract these existing strings and generate all the code you just saw above.
If you don't want to have the Compose code generated by KSP, you can set the `lyricist.xml.generateComposeAccessors` arg to `"false"`, and you can write the code manually by following the instructions [below](#extending-lyricist).

Similar to the multi module setup, you must provide a few arguments to KSP. Lyricist will search for `strings.xml` files in the resources path. You can also provide a language tag to be used as default value for the `LocalStrings`. 
```gradle
ksp {
    // Required
    arg("lyricist.xml.resourcesPath", android.sourceSets.main.res.srcDirs.first().absolutePath)
    
    // Optional
    arg("lyricist.packageName", "com.my.app")
    arg("lyricist.xml.moduleName", "xml")
    arg("lyricist.xml.defaultLanguageTag", "en")
    arg("lyricist.xml.generateComposeAccessors", "false")
}
```

After the first build, the well-known `rememberStrings()` and `ProvideStrings()` (naming can vary depending on your KSP settings) will be available for use. Lyricist will also generated a `Locales` object containing all language tags currently in use in your project. 
```kotlin
val lyricist = rememberStrings(strings)

ProvideStrings(lyricist, LocalStrings) {
    // Content
}

lyricist.languageTag = Locales.PT
```

You can easily migrate from `strings.xml` to Lyricist just by copying the generated files to your project. That way, you can finally say goodbye to `strings.xml`.

## Extending Lyricist

<details><summary>Writing the generated code from KSP manually</summary>

Don't want to enable KSP to generate the code for you? No problem! Follow the steps below to integrate with Lyricist manually.

1. Map each supported language tag to their corresponding instances.
```kotlin
val strings = mapOf(
    Locales.EN to EnStrings,
    Locales.PT to PtStrings,
    Locales.ES to EsStrings,
    Locales.RU to RuStrings
)
```

2. Create your `LocalStrings` and choose one translation as default.
```kotlin
val LocalStrings = staticCompositionLocalOf { EnStrings }
```

3. Use the same functions, `rememberStrings()` and `ProvideStrings()`, to make your `LocalStrings` accessible down the tree. But this time you need to provide your `strings` and `LocalStrings` manually.
```kotlin
val lyricist = rememberStrings(strings)

ProvideStrings(lyricist, LocalStrings) {
    // Content
}
```
</details>

<details><summary>Supporting other UI Toolkits</summary>

At the moment Lyricist only supports Jetpack Compose and Compose Multiplatform out of the box. If you need to use Lyricist with other UI Toolkit (Android Views, SwiftUI, Swing, GTK...) follow the instructions bellow.

1. Map each supported language tag to their corresponding instances
```kotlin
val translations = mapOf(
    Locales.EN to EnStrings,
    Locales.PT to PtStrings,
    Locales.ES to EsStrings,
    Locales.RU to RuStrings
)
```

2. Create an instance of Lyricist, can be a project-wide singleton or a local instance per module
```kotlin
val lyricist = Lyricist(defaultLanguageTag, translations)
```

3. Collect Lyricist state and notify the UI to update whenever it changes
```kotlin
lyricist.state.collect { (languageTag, strings) ->
    refreshUi(strings)
}

// Example for Compose
val state by lyricist.state.collectAsState()

CompositionLocalProvider(
    LocalStrings provides state.strings
) {
    // Content
}
```
</details>

## KSP 2.0 Configuration

Lyricist uses KSP 2.0 for optimal performance and multiplatform compatibility. The following `gradle.properties` configuration is recommended for best results:

```properties
# Enable KSP 2.0 architecture for K2 compiler compatibility and performance improvements
ksp.useKsp2=true

# Enable incremental compilation for dramatically faster builds (20-50% improvement)
# Only reprocesses changed files instead of regenerating everything from scratch
ksp.incremental=true

# Disable incremental compilation logging for cleaner build output
# Enable temporarily (ksp.incremental.log=true) when debugging KSP issues
ksp.incremental.log=false
```

## Troubleshooting

<details><summary>Can't use the generated code on my IDE</summary>

You should set manually the source sets of the generated files, like described [here](https://github.com/google/ksp/issues/37).
```gradle
buildTypes {
    debug {
        sourceSets {
            main.java.srcDirs += 'build/generated/ksp/debug/kotlin/'
        }
    }
    release {
        sourceSets {
            main.java.srcDirs += 'build/generated/ksp/release/kotlin/'
        }
    }
}
```
</details>

<details><summary>Slow incremental builds or frequent clean builds needed</summary>

Verify your KSP 2.0 configuration includes:
```properties
ksp.useKsp2=true
ksp.incremental=true
```

For debugging incremental compilation issues, temporarily enable:
```properties
ksp.incremental.log=true
ksp.verbose=true
```

Remember to disable these flags after debugging as they increase build output verbosity.
</details>

<details><summary>"Overload resolution ambiguity" errors between build variants</summary>

This typically occurs when debug and release variants see each other's generated code. Ensure your Android module uses proper source set isolation:

```gradle
// In your android module gradle file
sourceSets {
    debug {
        java.srcDirs += 'build/generated/ksp/debug/kotlin'
    }
    release {
        java.srcDirs += 'build/generated/ksp/release/kotlin'
    }
}
```

Avoid configuring source sets inside `buildTypes` blocks as this can cause variant conflicts with KSP 2.0.
</details>

## Import to your project

1. Importing the [KSP plugin](https://github.com/google/ksp/blob/main/docs/quickstart.md#use-your-own-processor-in-a-project) in the project's `build.gradle` then apply to your module's `build.gradle`
```kotlin
plugins {
    id("com.google.devtools.ksp") version "${ksp-latest-version}"
}
```

2. Add the desired dependencies to your module's `build.gradle`
```kotlin
// Required
implementation("cafe.adriel.lyricist:lyricist:${latest-version}")

// If you want to use @LyricistStrings to generate code for you
ksp("cafe.adriel.lyricist:lyricist-processor:${latest-version}")

// If you want to migrate from strings.xml
ksp("cafe.adriel.lyricist:lyricist-processor-xml:${latest-version}")
```

#### Version Catalog
```toml
[versions]
lyricist = {latest-version}

[libraries]
lyricist = { module = "cafe.adriel.lyricist:lyricist", version.ref = "lyricist" }
lyricist-processor = { module = "cafe.adriel.lyricist:lyricist-processor", version.ref = "lyricist" }
lyricist-processorXml = { module = "cafe.adriel.lyricist:lyricist-processor-xml", version.ref = "lyricist" }
```

#### Multiplatform setup

Doing code generation only at `commonMain`. Currently workaround, for more information see [KSP Issue 567](https://github.com/google/ksp/issues/567)
```kotlin
dependencies {
    add("kspCommonMainMetadata", "cafe.adriel.lyricist:lyricist-processor:${latest-version}")
}

tasks.withType<org.jetbrains.kotlin.gradle.dsl.KotlinCompile<*>>().all {
    if(name != "kspCommonMainKotlinMetadata") {
        dependsOn("kspCommonMainKotlinMetadata")
    }
}

kotlin.sourceSets.commonMain {
    kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin")
}
```

Current version: ![Maven metadata URL](https://img.shields.io/maven-metadata/v?color=blue&metadataUrl=https://s01.oss.sonatype.org/service/local/repo_groups/public/content/cafe/adriel/lyricist/lyricist/maven-metadata.xml)