CASH Platform Translations
Hey! You're here probably because you volunteered to write translations for the CASH Music Platform. Chances are you're pretty awesome. Translations are still a work in progress, but you can currently translate a large chunk of the text displayed on the admin, along with help files and element defaults.
The nice thing about most platform text is that it exists in external files, which makes it super easy for us to create translations, even with minimal technical knowledge of how the files are actually parsed.
One thing that we ask is to please, please not submit machine translations from services like Google Translate, etc. We need real, human translations.
The text files consist of two formats: JSON and Markdown. JSON is a text based way to store data, that's really easy to read and to parse. Markdown on the other hand is just a simple way to add styles and links to text, that will then be converted into HTML to display in the browser.
Note that we don't need any translations in the base vendor/ directory; these are all composer dependencies that never get displayed on the platform, and any changes will be destructively lost any time we update them.
Since both JSON and Markdown files are plain text, we need to make sure you're using the right kind of editor. It's important because many of the stock text editors that come with operating systems tend to add styles and formatting that will mess up these files and will overall just ruin Christmas.
A lot of us on the CASH team use Atom Editor. It's free and it does all these things--- and also works on Windows, OSX, and Linux.
You're also going to want to grab a copy of the CASH Platform code from Github . We suggest if you're not comfortable with using a versioning system like Git, to just download a ZIP file of the entire platform directly to your computer.
We'll be working with both sections within larger files, and also dedicated directories with text files that need to be translated.
The files we'll be editing are located in both the framework and interfaces directories. Let's look at framework first.
In the elements directory you'll see a bunch of sub-directories called things like "digitalpurchase", "downloadcodes", etc.
These are the elements like purchase elements, tour dates, etc that show in public. Each directory has an app.json file in it that you can open and translate directly in. If you look through the file there is for example a "details" section that includes several translations already.
"details":{
"en":{
"name":"Digital Purchase",
"description":"Choose this element if you are looking to sell one item. Great for preorders. ",
"longdescription":"Just want to sell one thing? Set up a simple single purchase element for the commerce item of your choice.",
"instructions":"This element type has been depreciated. It will continue to work, but consider migrating to the Single Purchase element."
},
"is":{
"name":"Stafræn Kaup",
"description":"Veldu þessa einingu ef þú vilt selja einn hlut. Hentugt fyrir forpantanir. ",
"longdescription":"Langar bara að selja einn hlut? Settu upp einfalda verslunar einingu fyrir stakan hlut að eigin vali.",
"instructions":"Þessi eining hefur verið afskrifuð. Hún mun halda áfram að virka, en íhugaðu að skipta yfir í Stök Kaup einingu."
}
}
You can see the translations as what's called a key:value pair. The key is the language code (i.e. en, fr, de, es, is) and the value in this case is an array of values (name, description, longdescription).
So what we'd do is:
-
copy the English key:value pair. Important: We recommend to always start with a copy of
enso we're not playing a game of transliteration telephone, for both key:pairs and also whole directories. -
add a comma after the last language key:pair (Icelandic in this case)
-
paste the English key:pair in after that comma, change the key name to the language code, and get translating!
There are other sections of each of these app.json files where you'd do the same thing as above. Scroll through and you'll see sections for copy and options as well. Remember always though: translate the value, not the key. The key is how we map the text on the code level.
These files are copy for admin facing components like menus.
The same idea applies here with the JSON editing, but we're dealing with directories instead of small sections of files. If you look at interfaces/admin/components/interface you'll see a whole directory for each language, based on the language code. Really all you need to do is copy the en directory and rename the copy to whatever language code you're translating to. Then you can go ahead and translate all of the values without having to worry about messing with other languages.
This directory is where we partially depart from the magical land of JSON and end up with Markdown. It's the same situation as the interface directory above, where each language is represented in it's own directory.
The help directory is where we encounter Markdown. This should be a little more straightforward than JSON editing--- but keep in mind that you'll want to retain any formatting or HTML tags that are already in the text, if at all possible.
Otherwise the pages directory is JSON, but without the language keys because the entire directroy is for the language you're translating to!
That's really it--- it seems like a lot of text to translate but it's not bad, we promise!
If you want to go the extra step, when you're done editing a JSON file, you can validate the formatting online via JSONLint.