Another Translation Question - what is the differenceb between {{ }} and ^{ }

I'm looking at translations for rolltemplates, and the text on the wiki page raises a few questions. This is the entire text on the wiki page:

Roll Templates

Static HTML inside of the sheet's roll template definition can use all of the above tools, including Dynamic Keys. If it is in the sheet's rolltemplate definition, code like {{strength-key}} will give the translated value of whatever is the value of {{strength-key}}. If you would like to send dynamically translated values inside of a roll function, use the tool below.

Inside of a roll function, using a roll template, you can wrap any text in ^{ [key] } to denote the text as a translation key. This text will be replaced with the translated version associated with that key. This step happens after character sheet values are swapped in, so ^{ @{ability_key} } where ability_key = STRENGTH will be parsed as ^{STRENGTH} and will display whatever translation value you have for STRENGTH. This also works on the key, for the key/value pairs used in the allprops() function.

Example: {{^{TEXT}=@{content} }} will have the translation value for TEXT as {{key}} inside of the allprops() function.

1. Does this mean you can use getTranslationByKey inside a rolltemplate, or just in a sheet worker script block?
2. What does this text mean? "If it is in the sheet's rolltemplate definition..."
3. It syas translation keys can be used inside {{ }} but it also translation keys can be used inside ^{ }. Is there a difference between those two usages? Is ione only valid in certain situations?
4. The example uses ^{ @{ability_key} }. I was under the impression that attributes themssleves couldm't be translated. What is being said here?
5. Can you explain what is being said with the mention of allprops?

This is a particularly confusing section.

GiGs said:

1. Does this mean you can use getTranslationByKey inside a rolltemplate, or just in a sheet worker script block?
2. What does this text mean? "If it is in the sheet's rolltemplate definition..."
3. It syas translation keys can be used inside {{ }} but it also translation keys can be used inside ^{ }. Is there a difference between those two usages? Is ione only valid in certain situations?
4. The example uses ^{ @{ability_key} }. I was under the impression that attributes themssleves couldm't be translated. What is being said here?
5. Can you explain what is being said with the mention of allprops?

This is a particularly confusing section.

1. Not quite. You can use getTranslationByKey in a sheetworker function using CRP just like you could in any sheetworker, however the output value will be the same for all users regardless of their translated language. ^{...} allows you to have content that is dynamically translated for all users regardless of their language. ^{...} is put in the actual roll expression that is sent to chat.
2. The same with any translation. If you don't have that key in your translation.json, then it won't be translated. On sheets, this is the cause of the red text surrounded by square brackets. ^{...} that calls a non existent behaves similarly, but the text will be whatever color that section of the roll template text should be instead of red.
3. You can only use ^{...} inside roll template fields. E.g. just sending ^{my-key} to chat by itself will just output ^{my-key}, but sending &{template:default} {{^{my-key}}} will output the translated value of my-key. See example image below.
4. I'm actually not entirely sure what's being said here, but here's my best guess. I think it's saying that the allProps function will get the sending user's translation value for the key. This would honestly only be important if a user sends a translation key as a custom key, but the value of that translation is one of the field names you told allProps to ignore.

Example image for #3:

Thank you, Scott. That's very informative. i think I follow most of what you're saying. I have a few follow up questions in reaction.

1. Your question 1 ansdwer is interesting. Are you saying there's a difference in behaviour between getTranslationBy key and ^{ }?
   
2. You don't acknowledge the {{ }} method at all - is that usable, or inferior to the ^{ } method?

GiGs said:

Thank you, Scott. That's very informative. i think I follow most of what you're saying. I have a few follow up questions in reaction.

1. Your question 1 ansdwer is interesting. Are you saying there's a difference in behaviour between getTranslationBy key and ^{ }?
   
2. You don't acknowledge the {{ }} method at all - is that usable, or inferior to the ^{ } method?

1. getTranslationByKey gets the translation value for the person who triggered the sheetworker (I'm not sure how this resolves if the API is the triggerer). So, it can only ever return one translation value, and that value is locked once it's returned. ^{...} acts like adding data-i18n keys to an html element, but you can do it in the output of a roll button or startRoll. See example code below.
2. There is no {{...}} method. The {{...}} they are referring to are the roll template fields. You can't use ^{...} anywhere except inside a roll template field.

Example Code for #1:

getTranslationByKey

const strengthStr = k.getTranslationByKey('strength');
console.log('strengthStr:',strengthStr);
// For english the output would be => strengthStr: strength
// For spanish the output would be => strengthStr: fortaleza
// But, it will only return one of these to be used in the sheetworker.

vs. html data-i18n keys and ^{...} use in roll templates

<span data-i18n="strength"></span>
<input name="attr_strength" type="number" value=10>
<button type="roll" name="roll_strength" value="&{template:default} {{^{strength}=[[1d20+@{strength}]]}}"></button>

Everyone who views the html output or roll template output from the second set of code will see it translated to their language. But the output from the js will only be translated into the language of the user that triggered the sheetworker to run.

I should also note that ^{...} should only be used for things that are truly dynamic (e.g. the attribute name being used in a roll). Anything that is a static part of the roll template should be done in the roll template using data-i18n keys.

Thank you for those clarifications. That explains why I hadn't seen {{ }} before but had seen plenty of ^{ } ;)

I'm a little fuzzy on the definition of dynamic here. What akes the attribute name in a roll dynamic?

dynamic here means anything that would be the content of a template field. As an example, you might have a skill section, which has several skills, all with buttons of the format:

<button type="roll" name="roll_skill_name" value="&{template:my-template} {{roll_name=^{skill name}}} {{roll=[[1d20]]}}"></button>

e.g. acrobatics would look like:

<button type="roll" name="roll_acrobatics" value="&{template:my-template} {{roll_name=^{acrobatics}}} {{roll=[[1d20]]}}"></button>

We want to be able to translate whatever the contents of roll_name is, or use it as is in the case we're sending this roll for something with a user entered name (e.g. a weapon).

Now, using this same example, let's say that if roll_name isn't passed as part of the message we want the text "roll" to be used instead, and we want that translated. For this, we'll define it in the rolltemplate html using data-i18n instead.

{{#roll_name}}{{roll_name}}{{/roll_name}}
{{^roll_name}}
  <span data-i18n="roll"></span>
{{/roll_name}}

Aha, I see. Of course rollTemplates have a lot of dynamic fields, since the roll is so variable. I was thinking in much more static terms, forgetting that a rolltemplateb is used for many different rolls. Thanks for that explanation.

also, a note. While ^{...} is used in roll templates, it does not work inside inline rolls inside a roll template. This will just show the text ^{acrobatics} for the roll tag:

&{template:my-template} {{roll_name=^{skill name}}} {{roll=[[1d20[^{acrobatics}]]}}

That's useful to know. Is there a way to show tags like that in translations, or do you have to avoid them?

I usually translate using getTranslationById in the crp sheetworker so at least the person who sent the roll will be able to read the tags.

That sounds ike a good approach, and in any case, most groups using another language will share that language. There won't be too many mixed language groups.

Scott C. said:

vs. html data-i18n keys and ^{...} use in roll templates

<span data-i18n="strength"></span>
<input name="attr_strength" type="number" value=10>
<button type="roll" name="roll_strength" value="&{template:default} {{^{strength}=[[1d20+@{strength}]]}}"></button>

Everyone who views the html output or roll template output from the second set of code will see it translated to their language. But the output from the js will only be translated into the language of the user that triggered the sheetworker to run.

I think I've just realised something. The ^{ } syntax is designed for use in the roll macros as you have done with strength here. You don't place it in the rolltemplate code itself (the HTML on the sheet). Is that correct?

Yes, it's for use in macros, roll button values, and roll messages sent via sendChat.

Thanks for that clarification. I hadnt thought of the script / sendChat usage.

I have one hopefully final question on this topic: is there any way to handle keys dynamically in allprops() ?

Imagine you have a structure like this (this doesn't work).

     {{#allprops() title ^{stat-key} }}
         <div class="sheet-roll-title">{{key}}</div>
         <div class="sheet-roll-result">{{value}}</div>
      {{/allprops() title ^{stat-key}}}

Imagine you want to exclude a specific key from inclusion in the allprops() loop. Do you have to include all possible translations of something, or is there a dynamic code you can include there that will automatically catch translated words or phrases?

There isn't, but it shouldn't be a big issue. most of your field keys should be pretty unique anyways.

You're right it's not usually a big deal, but I am being exhasutive :) and making sure I'm not missing something.

If y'all notice any blatant error in the Translation wiki page, please update it.

Expanding the Roll Template-section with a full example of a translated roll template and clarifying that  {{ }}  is just the roll template syntax seems also a good idea. Also linking to source code of a live sheet that has a somewhat simple roll template which is translated would make sense.

I haven't touched translations in years, so can't really contribute anything as of now.

And yes, it could be nice if a js/npm implementation of ACSI could be made, one would surely be useful for introducing translations to a bunch of existing sheets.

Andreas J. said:

If y'all notice any blatant error in the Translation wiki page, please update it.

Personally, I think that page should be rewritten completely.

That page stands out because the rest of the wiki is very good. Not always clear to beginners because a lot of the documentation is geared to people who are already web designers, but that's not a bad thing. There's a lot of valuable, official documentation there, and that is written with a certain audience in mind, and users have added a huge amount to it. (Mainly you, the unsung hero of the wiki!)

The translation page though is just a mess. But the information it contains seems to be accurate - not wrong, just confusing. And most readers will not be keen or able to make changes, because they won't known how to change it and still be accurate. There's a massive barrier there.

I know I wouldn't have known where to start or what to do, and most people are a lot less knowledgeable than I am.

Since you're writing a translation guide, you might be interested in an update I just released for the K-scaffold Initializer that automates adding translation tags to existing character sheet files.

Thanks for the note. I'll check that out.