Resource keys in Respresso
A resource key (aka. name) works as an identifier for resources. Developers use them to reference the resource in the source code. This is why Respresso requires them.
Key validity in Respresso
As resource keys are used from source code they have strict roles when it comes to the valid characters and syntax. Unfortunately, there is no common format that unifies multiple platforms that is also easily readable. This is the reason why Respresso allows you to input anything as a key, but then it converts them to a format that is commonly used in the target format. This does not mean that there is no validity checks under the hood.
By default, Respresso transforms each key and ensures it outputs a valid file set at the end. This process is fully automatic and typically resolves most of the issues without bothering the users with naming restrictions.
Each converter has its own restrictions that are applied during the conversion but only if the converter is enabled in the Flow. This lets your developers enable/disable format and with them the restrictions that apply to the keys. Any invalid combination of keys will result in an error during the conversion.
Unrestricted keys might seem a bit odd from the end user perspective, but it results in a smoother collaboration across the whole team. Unfortunately, using this method, naming errors are visible only during the save. This might be a bit frustrating for newcomers, but when you get used to it, it will turn out pretty useful.
Respresso has a common method to transform keys. All converters (Processors) that use it have a configuration option that lets you modify the behaviour using the Flow. (The default config might differ for each converter/processor as it is configured to meet the most common needs.)
These configurations have two parameters.
- strategy: Define when to apply the transformation(s). To disable the transformation, select
never. To force the transformation select
invalidkeysapplies it only when the provided key is invalid in the target format. (Latter is not supported in some cases. In these cases, it defaults to
- transforms: A list of predefined transformations to be applied in an ordered manner. See the config docs for the options.
Respresso does its best to automatically avoid any error, but it can't fix the unfixable.
Please note that by default, Respresso comes with most converters enabled. This results in pretty strict key naming roles, especially for localizations. If you don't need an output format, just disable it in the Flow to get rid of its restrictions.
Duplicate (transformed) keys
As keys should behave as identifiers, you should not assign the same key/identified to multiple resources. This also applies to the transformed keys.
As a rule of thumb, whitespace, separator characters and non-english letters will be converted or erased during a transformation. You can see that this leads to information loss, thus it can cause the loss of uniqueness. For this reason, a non-exact duplicate may result in duplicate key error.
For example, all of the
Welcome screen greeting,
welcomeScreenGreeting localization keys will be transformed to the
welcome_screen_greeting key on Android.
When you use a non-english language for your keys, it can be even more surprising. E.g. all the
are usually transformed to the same
aaeeuuuuoooo English alphabet version.
Special characters will also be removed. E.g. all the
currency_£ keys are usually transformed to the same
Conflicting hierarchy of structured keys
In most cases, Respresso doesn't parse any additional information from your resource keys, but there are exceptions. When Respresso generates a structured JSON from your localizations, it uses a set of separator characters to split them to a hierarchy.
Disable the structured JSON processor in the Flow if you don't need it.
By doing so, you remove the restrictions of the JSON structure. Alternatively, you can change the separator character list
(keyDelimiters config parameter<
to something else, like
As the JSON format can't place string and an object to the same property, it throws an error for keys that would result in this kind of structure.
welcome_screen.title.tooltip keys together will result in an error when the
. character is treated as a separator.
To see why this is a problem, see the two JSON objects that need to be merged together:
"title": "My title"
"tooltip": "Useful tooltip"
In this case the
title property can not hold a string and a nested object at the same time.
As a solution, you can change the
welcome_screen.title key to
welcome_screen.title.label so they can be merged:
"label": "My title",
"tooltip": "Useful tooltip"