Working with Keys

Managing keys is one of the most relevant tasks when dealing with localization files and translations. PhraseApp provides useful tools an mechanisms to deal with a large number of keys and technical restrictions in complex translation projects.

Blacklisting keys

PhraseApp allows you to exclude keys. This includes:

  • pushing translations
  • pulling translations
  • being editable within the PhraseApp Context Editor

The blacklist is a powerful tool to handle issues with keys that should be managed manually rather than editable by everyone. Examples for blacklisted keys are:

  • date and time format strings
  • keys that include configuration
  • keys that cause issues when being managed with the phrase gem

A best practice would be to add those keys to your blacklist and manage them in a separate locale file in your application that is not processed or maintained by PhraseApp.

Because we know that there are some keys that cause issues when used with PhraseApp (especially in setups with Ruby on Rails), we add several keys to the blacklist when creating a new project, e.g

  • activemodel.errors.*
  • number.format*
  • number.currency*
  • number.percentage*
  • datetime.prompts*
If you only want to exclude keys from being picked up by the In-Context-Editor but still manage them with PhraseApp, you should consider the ignored keys setting.

Excluding translations

In some cases you might want to exclude keys only in certain locales. For this PhraseApp allows you to mark certain translations as excluded. A excluded translation will:

  • be excluded from export of the related locale.
  • be excluded from the related locale statistics (Even if the content is empty it is not counted as untranslated).
  • be visible but not editable in the translation editor.

You have two options to exclude translations for a key:

  • exclude a single translation in a locale within the translation editor.
  • exclude multiple translations by selecting the locales when creating or editing the key.

Limiting the number of characters allowed

PhraseApp lets you set the number of characters a translation can contain. The maximum characters allowed can be set under the “Advanced” tab when editing a key. When a maximum number of characters is defined, the character count will be displayed when editing translations for that key.

Max number of characters

Deleting unused keys

If you have made a lot of changes in your localization file or removed whole features from your application and want to delete keys only attached to these features, you probably want to remove these “orphaned” keys from the list of keys in PhraseApp as well. You can identify keys that no longer occur in your (master) localization file by uploading the file again to Translation Center via the browser.

After uploading the file you should see an indicator of how many keys are no longer mentioned in the master file in the “Keys unmentioned” column. Click on the “Delete unmentioned keys” button to get an overview of the keys that you might want to delete. Click the delete button to remove all of them in one step.


Further reading: