Lyricist
🌎
🌍
🌏
The missing I18N and I10N library for 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!
Development status: Lyricist will be in Beta until Compose and KSP become stable.
Features
- Simple API to handle locale changes and provide the current strings
- Multi module support
- Code generation with KSP
- Easy migration from
strings.xml - Compose for Desktop support
Limitations
- The XML processor doesn't handle
fewandmanyplural values (PRs are welcome)
Why Lyricist?
Inspired by accompanist library: music composing is done by a composer, and since this library is about writing lyrics strings, the role of a lyricist felt like a good name.
Usage
Take a look at the sample app and sample-multi-module 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, Set or even lambdas!
data class Strings(
val simpleString: String,
val annotatedString: AnnotatedString,
val parameterString: (locale: String) -> String,
val pluralString: (count: Int) -> String,
val listStrings: List<String>
)
Next, create instances for each supported language and annotate with @Strings. The languageTag must be an IETF BCP47 compliant language tag (docs). You must flag one of them as default.
@Strings(languageTag = Locales.EN, default = true)
val EnStrings = Strings(
simpleString = "Hello Compose!",
annotatedString = buildAnnotatedString {
withStyle(SpanStyle(color = Color.Red)) { append("Hello ") }
withStyle(SpanStyle(fontWeight = FontWeight.Light)) { append("Compose!") }
},
parameterString = { locale ->
"Current locale: $locale"
},
pluralString = { count ->
val value = when (count) {
1 -> "a single apple"
2 -> "two apples"
in 3..10 -> "a bunch of apples"
else -> "a lot of apples"
}
"I have $value"
},
listStrings = listOf("Avocado", "Pineapple", "Plum")
)
@Strings(languageTag = Locales.PT)
val PtStrings = Strings(/* pt strings */)
@Strings(languageTag = Locales.ES)
val EsStrings = Strings(/* es strings */)
@Strings(languageTag = Locales.RU)
val RuStrings = Strings(/* ru strings */)
Lyricist will generate the LocalStrings property, a 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.
val lyricist = rememberStrings()
ProvideStrings(lyricist) {
// Content
}
Writing the code for yourself
Don't want to enable KSP to generate the code for you? No problem! Follow the steps below to integrate with Lyricist manually.
First, map each supported language tag to their corresponding instances.
val strings = mapOf(
Locales.EN to EnStrings,
Locales.PT to PtStrings,
Locales.ES to EsStrings,
Locales.RU to RuStrings
)
Next, create your LocalStrings and choose one translation as default.
val LocalStrings = staticCompositionLocalOf { EnStrings }
Finally, 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.
val lyricist = rememberStrings(strings)
ProvideStrings(lyricist, LocalStrings) {
// Content
}
Now you can use LocalStrings to retrieve the current strings.
val strings = LocalStrings.current
Text(text = strings.simpleString)
// > Hello Compose!
Text(text = strings.annotatedString)
// > Hello Compose!
Text(text = strings.parameterString(lyricist.languageTag))
// > Current locale: en
Text(text = strings.pluralString(1))
Text(text = strings.pluralString(2))
Text(text = strings.pluralString(5))
Text(text = strings.pluralString(20))
// > I have a single apple
// > I have two apples
// > I have a bunch of apples
// > I have a lot of apples
Text(text = strings.listStrings.joinToString())
// > Avocado, Pineapple, Plum
Use the Lyricist instance provided by rememberStrings() to change the current locale. This will trigger a recomposition that will update the strings wherever they are being used.
lyricist.languageTag = Locales.PT
Important: Lyricist uses the System locale as default. It won't persist the current locale on storage, is outside its scope.
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.
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.
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.
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")
}
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.
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.
Troubleshooting
Can't use the generated code on my IDE
You should set manually the source sets of the generated files, like described here.
buildTypes {
debug {
sourceSets {
main.java.srcDirs += 'build/generated/ksp/debug/kotlin/'
}
}
release {
sourceSets {
main.java.srcDirs += 'build/generated/ksp/release/kotlin/'
}
}
}
Import to your project
- Importing the KSP plugin in the project's
build.gradlethen apply to your module'sbuild.gradle
buildscript {
dependencies {
classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:${ksp-latest-version}"
}
}
apply plugin: "com.google.devtools.ksp"
- Add the desired dependencies to your module's
build.gradle
// Required
implementation "cafe.adriel.lyricist:lyricist:${latest-version}"
// If you want to use @Strings to generate code for you
compileOnly "cafe.adriel.lyricist:lyricist-processor:${latest-version}"
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}"
Current version:
14 Dec 21, 2022
23 Aug 24, 2022
9 Jul 5, 2022
43 Dec 29, 2022
10 Nov 23, 2022
59 Dec 14, 2022
3 Jun 20, 2022
4 Oct 10, 2022
689 Dec 25, 2022
5 Dec 29, 2022
5 Apr 5, 2022
38 Sep 25, 2022
186 Jan 1, 2023
382 Jan 5, 2023
3 Dec 31, 2022
1 Aug 11, 2022
180 Jan 2, 2023
3 Dec 15, 2022
548 Jan 7, 2023