Revision as of 23:52, 30 March 2016

Character sheet i18n, or internationalization, will allow you to design your character sheet in such a way that our community of translators will be able to translate your sheet into their language, making that language available to anyone on Roll20. If your sheet has been translated into another language, say French, and someone using your sheet has their account language set to French your sheet will show up with the translated texts for that user.

Designing Your Sheet

Setting up your sheet to be able to respond to the i18n service is very simple, it just can take some time, especially if you are working with a large pre-existing sheet. There are 2 steps you must take to allow your sheet to be translated. Step one, mark the elements that you want to contain the translated text. Step two, create a translations file that contains all of the strings that will be translated. This file will be fed to our translation service, Crowdin, where our volunteers can go string-by-string and translate them into another language. This will generate the same translation file in all of the other languages, which we will then use accordingly when someone has that language selected on Roll20.

Step One, Sheet Formatting

You will want to add the "data-i18n=[unique-key]" attribute to every element that has text in it that you want translated, you want to keep all of the text that is already there , or will be there, in the element because it can be used to generate your translation file for you when you are done (explained later). It is especially important that the text stays there while the sheet-i18n code is only on Dev, otherwise your sheet will no longer work on the main site until sheet-i18n makes it to main.

Standard Text

<div class="col">
    <div class="row">
        <span data-i18n="acrobatics-u">ACROBATICS <span>(Dex)</span></span>
        <input class="num" type="text" name="attr_npc_acrobatics" placeholder="0">
    </div>
    <div class="row">
        <span data-i18n="animal-handling-u">ANIMAL HANDLING</span>
        <input class="num" type="text" name="attr_npc_animal_handling" placeholder="0">
    </div>
    <div class="row">
        <span data-i18n="arcana-u">ARCANA</span>
        <input class="num" type="text" name="attr_npc_arcana" placeholder="0">
    </div>
    <div class="row">
        <span data-i18n="athletics-u">ATHLETICS</span>
        <input class="num" type="text" name="attr_npc_athletics" placeholder="0">
    </div>
    <div class="row">
        <span data-i18n="deception-u">DECEPTION</span>
        <input class="num" type="text" name="attr_npc_deception" placeholder="0">
    </div>
    <div class="row">
        <span data-i18n="history-u">HISTORY</span>
        <input class="num" type="text" name="attr_npc_history" placeholder="0">
    </div>
</div>

Notice how every span in this code block has the data-i18n attribute with a key that references the text contained in the span. Also notice that there is HTML within the span, this is totally fine. The HTML will be marked by Crowdin so it is easy for them to copy and paste the HTML into their translation. While HTML is okay inside of the translation, try and keep it as simple as possible because the translators are most likely no code-savey and may have issues copying the code if it's not super simple. The text within the span will be replaced when the sheet is loaded, but the text should be left there because of the reasons mentioned above. It is very important that every unique string has a unique key, notice that since this text is in all caps I'm using a -u at the end of each key. That is because these words show up later in the sheet, but are cased normally.

There are some cases where you will want to add extra context to the key that the translator might not get from the the text alone, like with abbreviations.

<div class="row">
    <span data-i18n="components:-u">COMPONENTS:</span>
    <input type="checkbox" name="attr_spellcomp_v" value="{{v=1}}" checked="checked">
    <span data-i18n="spell-component-verbal">V</span>
    <input type="checkbox" name="attr_spellcomp_s" value="{{s=1}}" checked="checked">
    <span data-i18n="spell-component-somatic">S</span>
    <input type="checkbox" name="attr_spellcomp_m" value="{{m=1}}" checked="checked">
    <span data-i18n="spell-component-material">M</span>
    <input type="text" name="attr_spellcomp_materials" accept="Material" style="margin-left: 17px; width: 215px;" placeholder="ruby dust worth 50gp" data-i18n-place="ruby-dust-place">
</div>

Notice the keys for the V, S, and M texts spells out exactly what the single character is referring to. Otherwise the translator would have no idea what "V" means. This way the translator can change V to the first letter of whatever "Verbal" is in their language, if it is different.

Placeholder Text

If you have an element that has placeholder text that you want replaced, you can use the "data-i18n-place" attribute exactly like above. Only now instead of replacing the text in the element, it will replace the text within the "placeholder" attribute. You can see an example of this in the text above, as well.

Variable Replacement

One last special case is if you have text within a string that you do not want translated you can use special variables and the "data-i18n-vars" attribute.

<span data-i18n="var-test" data-i18n-vars="will not|be translated">This text {{0}} {{1}}</span>

The text inside of the data-i18n-vars attribute will be divided by the "|" character and placed in an array. You can then reference that array using {{[row]}} to reference the specific row of the array.

Generating the Translation File

Once you have formatted your sheet, following the instructions above. You can very easily create your translation file, if you followed the instructions to put the default text in the elements you want translated. After loading your sheet within the editor, open the developer tools and go to the console. At the very bottom of the console, where you can enter code, type "i18nOutput". (it will most likely start to auto-complete once you start typing) Hit enter to retrieve this object, and it will dump a json string containing all of the keys you have used with the corresponding text from within the element/placeholder. You should be able to then copy this text into your favorite JSON formatter (optional, but recommended) and then into the "Translation" tab in the Game Settings Custom Sheet area. Once you have your formatted sheet and the translation JSON saved for your custom sheet, it should look exactly like it did before you translated everything, assuming everything was done correctly.

If you see any red text like [translation-key] this is a key that you are telling the system to use, but have not entered into the translation JSON. If you use the JSON generated by the system, you should not see any of these.

Once you have a working translation file, you can upload this with the rest of your sheet code to the root of your character sheet folder as "translation.json". This will automatically be picked up by our system and uploaded to Crowdin, where it can then be translated.