feat: Add translation key prefixes for upload and download

[malvarezphrase]

Purpose: Provide documentation for the new params on import and export.

Pushing:

• provide a prefix with translation_key_prefix which will be prepended to the name of the imported translation keys
• provide <file_name> as the translation_key_prefix to use the file path of the pushed file as a prefix

Pulling:

• provide a prefix with translation_key_prefix which will be subtracted from the name of the exported translation keys. Warning: this may create duplicate key names if other keys share the same name after the prefix is removed
• provide <file_name> as the translation_key_prefix to use the file path of the pulled file as a prefix
• set the option use_translation_key_prefix_as_filter to true for the prefix to work as a filter. In this case only translation keys including the provided prefix in their name will be exported

Related tickets:
https://phrase.atlassian.net/browse/STRINGS-374
https://phrase.atlassian.net/browse/STRINGS-439

[malvarezphrase]

@theSoenke & @jablan Let me know if I missed anything 🙏
And as far as I understood we release this once we untoggle the feature, right?

[jablan]

hey @malvarezphrase can you please explain the logic with the truncating file name? I don't get it.

[malvarezphrase]

hey @malvarezphrase can you please explain the logic with the truncating file name? I don't get it.

@jablan The reason for the truncate of the file name is that we want to use the idx_translation_keys_on_name_project_deleted index on translation keys when the prefix is used as a filter. Therefore we only allow it to be maximum 255 characters long.

Now looking at the other usages of the prefix, is it also possible to add a limit on create.yaml and download.yaml? Or will phrase respond with a validation error?

[jablan]

@malvarezphrase sorry, I need a bit more context. where does <file_path> come from? is that a "magic" prefix working similar to <locale_code> and such? is it explained somewhere?

[malvarezphrase]

@malvarezphrase sorry, I need a bit more context. where does <file_path> come from? is that a "magic" prefix working similar to <locale_code> and such? is it explained somewhere?

@jablan Yeah, it should be working like <locale_code>, so when <file_path> is given as the prefix, we want to use the actual file path as the prefix. But you're right, I'm missing the explanation. Where would I put it?

[jablan]

Where would I put it?

@malvarezphrase I would start with the ticket description 😄 and probably the PR description too, as that stays longer. especially knowing that this repo is public.

if it can be specified only through the phrase.yml, probably we should document it in https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/phrase.json
but I don't see other magic placeholders either, so perhaps it's a good opportunity to add them all?

regarding the truncating, if I understand you correctly, we don't support prefixes longer than 255 chars? in that case we should probably error out rather than truncating them?

[malvarezphrase]

@jablan Thanks a lot for the feedback! I already updated the ticket descriptions and also the description of this PR.

Are the changes to https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/phrase.json being done manually? If so, I will prepare a PR for it.

in that case we should probably error out rather than truncating them?
How do errors on the CLI usually work? The validation for the length is already in place inside phrase.

[jablan]

perhaps then just passing whatever prefix is provided (either explicitly by the user or by using the filename) will be enough. is the error clear to the user?

as for json schema, perhaps you could open a small ticket, I see couple other things that could be fixed there, so we will do it all together.

just remember, we also have https://support.phrase.com/hc/en-us/articles/5808300599068-Using-the-CLI-Strings where we might want to describe this feature?

[malvarezphrase]

@jablan & @theSoenke after changing to not truncate the length of the prefix and updating the description here, is there anything else missing?

[jablan]

hm not 100% sure but I think at this point target.File can still contain other placeholders, i.e. it won't be the path to the actual file. can you double check this?

[theSoenke]

That's important! Really good catch and it does still contain placeholders at this point

[theSoenke]

@jablan @malvarezphrase I've changed the file_path placeholder to make it work with other placeholders. It's also now possible to use the placeholder as part of the prefix like <file_path>-foo. Having the ability to separate the path from the key name by characters seems useful when I was testing it

[jablan]

👌