Managing Local ArchivesSpace Custom Labels

About custom ArchivesSpace labels

All the labels, messages, and tooltips displayed on ArchivesSpace can display custom text. ArchivesSpace can take your desired text, and translate the out-of-the-box text to your custom text.

“Out of the box” example:	Customized example:

ArchivesSpace has abstracted all of the text out of the application into “locales” files. A locale file contains a set of translations for text strings. Each application may add to or override these values through these locales files.

ArchivesSpace maintains "translations" files in the following files

ArchivesSpace provides these locales files so users can customize and manage labels, messages, or tooltips in centralized files.

(Note: In each of these directories, you may notice there are several files listed. ArchivesSpace maintains a separate locale file for every language currently available in the application.)

Maintaining your custom ArchivesSpace labels

If you've made modifications to your locales file ( en.yml ) with customized labels, messages, tooltips, etc., you'll need to transfer those to your new locale file at the time of each ArchivesSpace version upgrade.

When ArchivesSpace releases an upgrade, it is possible that new features are added to the release. In order to ensure the new features have human-readable translations, you will need to maintain your locales files.

For example, your ArchivesSpace labels were last updated with custom labels in October 2017. However, ArchivesSpace releases a new feature, such as a new Assessments Module, in November 2017. The new version released in November 2017 includes translations for never-before-seen Assessments labels. Without these new translations in your customized locales files, your upgraded ArchivesSpace labels will likely look like this:

Updating your custom ArchivesSpace labels

To update and maintain your custom ArchivesSpace labels at the time of each new ArchivesSpace upgrade, we’ll need to take the following steps:

Step 1: Find your custom locales files.

Your CDL-hosted locales files are available in this directory: https://github.com/cdlib/pad-aspace/tree/main/client_config

Step 2: Find the ArchivesSpace locales file templates.

Note: The ASpace URLs currently link to their "master" build. Please be sure to grab the ASpace files from their latest version build: https://github.com/archivesspace/archivesspace/releases

Step 3: What’s the diff?

Compare the differences between your custom file, and the new upgraded file, to identify all of your custom labels. You may run a comparison between your current locales files, against the new version locales files. Use a Diff tool, provided in Notepad++ or TextMate, or run a Linux diff command.

Option: TextMate

• Open TextMate

• Copy and paste the text from your customized file into TextMate

• Copy the text from the upgraded out-of-the-box file

• On the menu, choose: Bundles > Diff > “Document with Clipboard”

• The result will show the difference between the two files:

Option: Linux diff command

 $ diff /path/to/archivesspace-1.4.2/locales/en.yml /path/to/archivesspace-1.5.x/archivesspace/locales/en.yml

 $ diff /path/to/archivesspace-1.4.2/locales/enums/en.yml /path/to/archivesspace-v1.5.x/archivesspace/locales/enums/en.yml

Running a Diff will identify the difference between your current locales files, against the new version locales files.

Step 4: Replace snippets of the new ArchivesSpace locales files with your custom labels.

Option: Use a text editor, and email over the files.

• Use a text editor, such as Notepad++, TextMate, or Atom.
• Go to the latest ArchivesSpace release, grab the locales files, and the files in your text editor.
• Copy the values you wish to keep from your old ArchivesSpace locales and paste it into your new ArchivesSpace locales files, at the appropriate locations in the files.
• Save a back-up of your older file, in case we need to restore it.
• Rename your new file to match your old filename.
• Send your replacement file as an attachment to oacops@cdlib.org. We will replace your file at the time we upgrade all CDL-hosted ArchivesSpace instances to the latest ArchivesSpace release.

Option: Edit the file on Github, and submit a pull request.

• Open up the file you need to edit.
• Choose the "pen" icon to go into edit.
• Copy the values you wish to keep from your old ArchivesSpace locales and paste it somewhere handy (in a separate text editor)
• Copy all of the values from the new ArchivesSpace locales, and paste it into your old file (on Github)
• Paste (and overwrite) only the values you wish to carry over from your old to your new.
• At the bottom of the page, write in a description of your changes, and propose the change.
• The next page will feature a new button, that says "Create pull request" -- choose this button.
• A box will appear, and the description you entered earlier should re-populate. Push "Create pull request"
• Feel free to send over a heads up to oacops@cdlib.org to note that you've submitted your changes.

Note: Any customized en.yml locales files will need to be updated with each ArchivesSpace upgrade.

Further documentation available

ArchivesSpace maintains the most up to date documentation based on any changes they may include during version upgrades.

• Customizing text in ArchivesSpace
• ArchivesSpace Locales Readme
• ArchivesSpace Frontend Locales Readme