Revision as of 23:35, 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.

<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.

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.

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.