Translate your existing character sheets!

Hi fellow sheet authors! One of the most time consuming upgrades to do on an old character sheet is to add translation support to it. Doing this by hand for a large sheet might take months of work. However, there's now a better option. The K-scaffold initializer now provides automated translation creation for any project without needing to use the entire K-scaffold . To use this, you will need to install node.js and npm (which comes with node). If you aren't used to node/terminal operations, note that you always want to use the LTS (latest stable release) download from node. Once you have node installed, you can run the initializer in the folder containing the html for your character sheet. The command is: npx @kurohyou/k-init This will install and run the initializer on your node, which will then prompt you to either setup a K-scaffold project or translate an existing project. For an existing project, select the translate option. Your existing html file will be updated with translation keys, a new html file will be made that will contain your original html, and a translation.json file will be made as well. If demonstrations are more your speed, here's a gif of the translator in action: * NOTE: The gif shows using the command npx k-init . This was the command when testing on my local system. The actual command is npx @kurohyou/k-init  as described above (Thanks to GiGs for spotting that I had this wrong). I hope this helps existing sheets to add support for additional languages. Scott

This looks very, very handy. Just so I understand the limitations, does it add translations for title and placeholder tags? I assume default sheet setting translations still have to be added manually? Does it ignore sheet workers and rolltemplated? they provided problems for the older tool ACSI.

It handles any html at all, whether it's in the main sheet or the roll template. It also handles all of the translatable html element properties I'm aware of including title and placeholder. In the demo gif, you can see the title and aria-label properties get translated. Any translation that is done via sheetworker would need to be added manually, but I doubt many sheets that don't already have full translations are doing that.

That's awesome. I missed the title part in the gif despite looking for titles. Oops.

Awesome Scott!  Very timely btw...  I've used Andreas ACSI in the past which saved me a lot of time.  The fact that this can be done from within my vscode environment, handles roll templates, and doesn't require the full K-Scaffold system, makes this a must have tool for any sheet author.  No more excuses for sheets not to have the translation code added.  Many thanks.

vÍnce said: The fact that this can be done from within my vscode environment This is the part I'm most excited by, and am looking forward to playing around with it. And by "playing around with it" I mean pressing enter a few times :)

This is fantastic! Do you know if it works on sheets which are partially translated? For instance, the Saga Edition sheet has a number of things marked with i18n, but none of the title text has it. Will this be an issue?

Thats a good question. Also for partial in another sense: where you have say the title translation already, but dont have the placeholder. Will the title get overwritten: <textarea title="look at me!" data-18m-title="look-at-me" placeholder="EXAMPLE TEXT">Example text</textarea> Missing: a basic translation (data-18m) and placeholder (data-18n-placeholder. Present: title (data-18n-title) What happens here?

Currently I hadn't considered those use cases, but handling for that would be relatively easy to add to the initializer (I think like one line of code). Actually, it might already work. I'll test in a minute.

Well, it almost works. It's actually revealed a bug that I'll get fixed today.

GiGs said: Thats a good question. Also for partial in another sense: where you have say the title translation already, but dont have the placeholder. Will the title get overwritten: <textarea title="look at me!" data-18m-title="look-at-me" placeholder="EXAMPLE TEXT">Example text</textarea> Missing: a basic translation (data-18m) and placeholder (data-18n-placeholder. Present: title (data-18n-title) What happens here? This has now been fixed. If the html is partially translated, the existing translation keys will be used. If there is content for the untranslated version of the data-i18n version of the key, that will be used as the value for the key in the translation.json, but if no untranslated text is provided, then the translation key and value will be the same. To demonstrate, imagine we have the following partially translated html: <span>span content</span> <section aria-label="section label"> <span>some label</span> <span type="text" data-i18n-title="title-key" alt="alt text" name="attr_test" title="title text" data-i18n="span content"></span> </section> The translated html would be: <span data-i18n="span content">span content</span> <section aria-label="section label" data-i18n-aria-label="section label"> <span data-i18n="some label">some label</span> <span type="text" data-i18n-title="title-key" alt="alt text" name="attr_test" title="title text" data-i18n="span content" data-i18n-alt="alt text"></span> </section> and the translation.json file will be: { "alt text": "alt text", "section label": "section label", "some label": "some label", "span content": "span content", "title-key": "title text" }

All right, thanks for checking on that!

Scott, how do you create your instructional gifs?

When i try to run this, i get an error. I've reinstalled node, and then after, opened a folder which contains some html files to translate, and type in the terminal npx k-init And this is what I see. How do I proceed from here?

I apparently screwed up the command. Needs to be npx @kurohyou/k-init

aha that seems to have workied. I got the translate option this time, and a file has translations in it. I dont have time for a thoroough check right now, but so far, yay!

GiGs said: Scott, how do you create your instructional gifs? I use a gif recorder called LICEcap .

Scott C. said: I apparently screwed up the command. Needs to be npx @kurohyou/k-init Is there any way to alias this to something shorter, like npx k-init ? Either done at your end, or a config setting at the client side? The longer title is okaay, I'm just looking at ease of use and user confusion.

on the npm server side, no unfortunately because it's a scoped package. On the user end, you can create an alias for it just like any command line command. How to do that is going to depend on a user's OS, but there are numerous guides for it out in the wilds of the net. I will note that it can actually be copy/pasted in to the terminal though; command line paste on windows is shift-insert . In the terminal in vscode you can also use normal ctrl-v .

I used CTRL+V muyself, but I'll look into how to create an alias (or add it to a menu). I do see this is a very useful tool. How does it handle situations where the same key is used in multiple places. Like say you start with <span data-i18n="Strength">Strength</span> And you late reuse the word Strength and want to add a translation key. Will the app handle that okay? (As i type this, I think the answer has to be yes, but it's worth asking anyway.)

if you had something like: <span data-i18n="Strength">Strength</span> <span>Strength</span> it'd work fine, because it'd see that the key already exists and wouldn't duplicate it in the translation.json file, and the key would be added to the second span. Similarly, if you had some sections already translated and had two different keys with the same content: <span data-i18n="Strength">Strength</span> <span data-i18n="ability-str-header">Strength</span> It'd work fine, because it doesn't care about matching values, just looks at the keys However, if you had a key that didn't match the content (e.g. that second span in the previous code block) and wanted future instances of that content (e.g. Strength) to use that key, it won't handle that. E.g. <span>Strength</span> <span data-i18n="ability-str-header">Strength</span> would result in: <span data-i18n="Strength">Strength</span> <span data-i18n="ability-str-header">Strength</span> There isn't really a good way to handle situations like that, but I'd also imagine the majority of sheets that this would be used for aren't going to be in a situation like that (aka small affected population, and minor effect). I suppose I could add an option to clear all existing keys so that the created translation.json uses a consistent key name scheme, but that would cause problems for those few sheets that are already partially translated because existing translations to other languages would be completely invalidated (aka, small affected population, but the effect is very large). I'll also note that users will need to manually remove keys from elements that shouldn't be translated (e.g. anything using the pictos fonts, dice fonts, material icons, or material symbols)

That's a great answer, very informative. You mention "I suppose I could add an option to clear all existing keys" and that makes me thing there could probably be a few configuring options (lien "replace all spaces with another character, like hyphens"), but there are problems with such approaches (the one I just mentioned leads to things like, replacing double characters with single characters, which then leads to an increasing possibly of different names being read as the same name). Other config options I can think of would be adding aliases (so Strength is always strengrh, say, or "Beyond the Fringe" is always "deep"), but I can see problems there. If you choose not to add any configuring options , it looks like it is good anyway. You've thought through a bunch of situations that hadn't occurred to me yet. If config options were added, it should be combined with a warning of the dangers of using them. They'd expand the program's capabilities, but require more work which isn't absolutely necessary. Cleating keys as a separate option does seem like a very good idea though, so you can clear out all translations in one fell swoop, then look at the file to see if it is harmed, while also keeping a backup of the original.

Yep, I think the only thing I might  add currently is the ability to pull from a pre existing translation.json file. But, I might not too. I can't imagine there's too many sheets that are partially translated since it's something that doesn't really have benefit unless you do the whole thing.

I think there might be some sheets with incomplete translations, but unintentionally, as a result og oversights or starting to add translations at a later point in the design. Your program will fill the gaps there.

I've waited to do translations on my current sheet work just so I can run it all at once.  I was worried about partial translation work. 

Make a backup copy of your existing sheet in a different folder . The program makes backups already (with a name prefix untranslated-) but it never hurts to be extra safe when trying something new. It will automatically add translations to all html files in the folder you choose. That way if something happens that doesn't fit your goal, you can go back to the original version easily.

Do you have a name for this tool, since it can be used separately from k-scaffold?

Nope, it's just the translation option of the K-scaffold initializer. There's no technical reason they couldn't be separated, but it was just easier for me to add it to an existing project than create a brand new project.

npx @kurohyou/k-init Is a gateway drug command to K-Scaffold. ;-p

Since it can be used separately, it really needs its own name. I might being selfish because I want to know how to refer to it on my blog :)

Heh, I thought so. K-scaffold Translator would probably be a decent name.

I finally got around to using this, and wow. That was fast. There are a number of things that I'll have to manually adjust, like all of the translations for things like <span data-i18n=" = "> = </span> And then the tags for the titles that have attributes... On one hand, it might be useful to have those available for translation. But on the other hand, I don't want translators to try translating the names of the actual attributes. I'll have to give that some thought. Also, do the translations actually work in rolltemplates? Anyway, thanks for the wonderful tool!

As I look at all of the different translation entries, I am reminded once more what an absolute piece of work this Saga Edition sheet is. I also learned what a self-closing tag is, and that a textarea is NOT something that can have it, when I saw this beauty in the translation file: "\t\t\t\t</div>\t\n\t\t\t</div>\n\n\t\t\t<!-- Armor section -->\n\t\t\t<div>\n\t\t\t\t<input type=\"checkbox\" class=\"sect-show sheet-hidden\" value=\"1\" name=\"attr_armor-show\" /> \n\t\t\t\t<div class=\"sect\">\n\t\t\t\t\t<input type=\"checkbox\" class=\"sheet-hidden sect-show\" name=\"attr_armor-section-show\" value=\"1\" checked=\"false\" id=\"show-armor-section-PC\" />\n\t\t\t\t\t<label for=\"show-armor-section-PC\" class=\"sheet-textHead2Col clickable\" data-i18n=\"armor\" title=\"Show/Hide Armor Section\">Armor</label>\n\t\t\t\t\t<table class=\"sheet-spacing sect sheet-table2col\" style=\"margin-bottom: 18px\">\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<th width=\"50%\" colspan=\"3\" class=\"sheet-small\">\n\t\t\t\t\t\t\t\tArmor Worn\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorWornCheck\" title=\"Armor equiped @{ArmorWornCheck}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Ref Def Bonus</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Fort Def Bonus</th>\t\t\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Max Dex Bonus</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Speed</th>\n\t\t\t\t\t\t</tr>\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<td colspan=\"3\">\n\t\t\t\t\t\t\t\t<input type=\"text\" name=\"attr_ArmorWorn\" style=\"width:100%\" title=\"Armor Name @{ArmorWorn}\" placeholder=\"Armor name\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorRef\" value=\"0\" title=\"Armor Reflex Defense Bonus @{ArmorRef}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorFort\" value=\"0\" title=\"Armor Fortitude Defense Bonus @{ArmorFort}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorDex\" value=\"0\" title=\"Armor Max DEX @{ArmorDex}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_Speed_max\" value=\"0\" title=\"Armor Max Speed @{Speed|max}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t</tr>\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">\n\t\t\t\t\t\t\t\t<br/>Proficiency<br />\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorProf\" title=\"Proficient in armor worn @{ArmorProf}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Armored Defense\n\t\t\t\t\t\t\t\t<br />\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorDefense\" title=\"Armor Specialist: Armor Defense @{ArmorDefense}\" />\n\t\t\t\t\t\t\t</th>\t\t\t\t\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Improved Armored Def.<br /><input type=\"checkbox\" value=\"1\" name=\"attr_ImpArmorDefense\" title=\"Armor Specialist: Improved Armor Defense @{ImpArmorDefense}\" /></th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\" colspan=\"2\">Armor Type<br/>\n\t\t\t\t\t\t\t\t<select name=\"attr_ArmorType\" style=\"width:90px\" title=\"Armor Type @{ArmorType}\">\n\t\t\t\t\t\t\t\t\t <option value=\"Light\">Light</option>\n\t\t\t\t\t\t\t\t\t <option value=\"Medium\">Medium</option>\n\t\t\t\t\t\t\t\t\t <option value=\"Heavy\">Heavy</option>\n\t\t\t\t\t\t\t\t</select>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorType_max\" value=\"0\" class=\"hidden\" title=\"Armor Penalty @{ArmorType|max}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\" colspan=\"2\">\n\t\t\t\t\t\t\t\tHelmet Package\n\t\t\t\t\t\t\t\t<br/>\n\t\t\t\t\t\t\t\t<select name=\"attr_ArmorPerception\" style=\"width:90px\" title=\"Helmet Package Perception bonus @{ArmorPerception}\">\n\t\t\t\t\t\t\t\t\t<option value=\"None\" selected>None</option>\n\t\t\t\t\t\t\t\t\t<option value=\"Standard\">Standard</option>\n\t\t\t\t\t\t\t\t\t<option value=\"Superior\">Superior</option>\n\t\t\t\t\t\t\t\t</select>\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t</tr>\t\n\t\t\t\t\t\t<tr></tr>\n\t\t\t\t\t\t<tr>\t\t\n\t\t\t\t\t\t\t<td colspan=\"7\"><textarea type=\"text\" name=\"attr_ArmorNotes\" class=\"atkNotes\" title=\"Armor Notes @{ArmorNotes}\" placeholder=\"Armor Notes\">": "</div>\t\n\t\t\t</div>\n\n\t\t\t<!-- Armor section -->\n\t\t\t<div>\n\t\t\t\t<input type=\"checkbox\" class=\"sect-show sheet-hidden\" value=\"1\" name=\"attr_armor-show\" /> \n\t\t\t\t<div class=\"sect\">\n\t\t\t\t\t<input type=\"checkbox\" class=\"sheet-hidden sect-show\" name=\"attr_armor-section-show\" value=\"1\" checked=\"false\" id=\"show-armor-section-PC\" />\n\t\t\t\t\t<label for=\"show-armor-section-PC\" class=\"sheet-textHead2Col clickable\" data-i18n=\"armor\" title=\"Show/Hide Armor Section\">Armor</label>\n\t\t\t\t\t<table class=\"sheet-spacing sect sheet-table2col\" style=\"margin-bottom: 18px\">\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<th width=\"50%\" colspan=\"3\" class=\"sheet-small\">\n\t\t\t\t\t\t\t\tArmor Worn\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorWornCheck\" title=\"Armor equiped @{ArmorWornCheck}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Ref Def Bonus</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Fort Def Bonus</th>\t\t\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Max Dex Bonus</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Speed</th>\n\t\t\t\t\t\t</tr>\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<td colspan=\"3\">\n\t\t\t\t\t\t\t\t<input type=\"text\" name=\"attr_ArmorWorn\" style=\"width:100%\" title=\"Armor Name @{ArmorWorn}\" placeholder=\"Armor name\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorRef\" value=\"0\" title=\"Armor Reflex Defense Bonus @{ArmorRef}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorFort\" value=\"0\" title=\"Armor Fortitude Defense Bonus @{ArmorFort}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorDex\" value=\"0\" title=\"Armor Max DEX @{ArmorDex}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t\t<td>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_Speed_max\" value=\"0\" title=\"Armor Max Speed @{Speed|max}\" />\n\t\t\t\t\t\t\t</td>\n\t\t\t\t\t\t</tr>\n\t\t\t\t\t\t<tr>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">\n\t\t\t\t\t\t\t\t<br/>Proficiency<br />\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorProf\" title=\"Proficient in armor worn @{ArmorProf}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Armored Defense\n\t\t\t\t\t\t\t\t<br />\n\t\t\t\t\t\t\t\t<input type=\"checkbox\" value=\"1\" name=\"attr_ArmorDefense\" title=\"Armor Specialist: Armor Defense @{ArmorDefense}\" />\n\t\t\t\t\t\t\t</th>\t\t\t\t\n\t\t\t\t\t\t\t<th class=\"sheet-small\">Improved Armored Def.<br /><input type=\"checkbox\" value=\"1\" name=\"attr_ImpArmorDefense\" title=\"Armor Specialist: Improved Armor Defense @{ImpArmorDefense}\" /></th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\" colspan=\"2\">Armor Type<br/>\n\t\t\t\t\t\t\t\t<select name=\"attr_ArmorType\" style=\"width:90px\" title=\"Armor Type @{ArmorType}\">\n\t\t\t\t\t\t\t\t\t <option value=\"Light\">Light</option>\n\t\t\t\t\t\t\t\t\t <option value=\"Medium\">Medium</option>\n\t\t\t\t\t\t\t\t\t <option value=\"Heavy\">Heavy</option>\n\t\t\t\t\t\t\t\t</select>\n\t\t\t\t\t\t\t\t<input type=\"number\" name=\"attr_ArmorType_max\" value=\"0\" class=\"hidden\" title=\"Armor Penalty @{ArmorType|max}\" />\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t\t<th class=\"sheet-small\" colspan=\"2\">\n\t\t\t\t\t\t\t\tHelmet Package\n\t\t\t\t\t\t\t\t<br/>\n\t\t\t\t\t\t\t\t<select name=\"attr_ArmorPerception\" style=\"width:90px\" title=\"Helmet Package Perception bonus @{ArmorPerception}\">\n\t\t\t\t\t\t\t\t\t<option value=\"None\" selected>None</option>\n\t\t\t\t\t\t\t\t\t<option value=\"Standard\">Standard</option>\n\t\t\t\t\t\t\t\t\t<option value=\"Superior\">Superior</option>\n\t\t\t\t\t\t\t\t</select>\n\t\t\t\t\t\t\t</th>\n\t\t\t\t\t\t</tr>\t\n\t\t\t\t\t\t<tr></tr>\n\t\t\t\t\t\t<tr>\t\t\n\t\t\t\t\t\t\t<td colspan=\"7\"><textarea type=\"text\" name=\"attr_ArmorNotes\" class=\"atkNotes\" title=\"Armor Notes @{ArmorNotes}\" placeholder=\"Armor Notes\">",

Yes, the translations will work inside roll templates. And, the json generated files definitely need some editing for more complex sheets, but it should hopefully get you pretty close.