Zu Hauptinhalten wechseln

FV Decipher Unterstützung

Alle Themen, Ressourcen für FV Decipher benötigt.

 
decipher

Resource Tag: Create Translatable Resources

Overview

Resource (<res>) tags are a great way to provide additional resources that can be used across your project. Resources reside in a Python dictionary and can be referenced from anywhere in the survey, nstyles file, error messages, <exit> tags, and external pages referenced from an <html> tag.

A resource tag will be picked up by the translation system and easily accommodated for in multi-language studies. Consider the following example:

<res label="currency">$</res>

<number label="Q1" size="4" verify="range(0, 9999)" ss:preText="${res.currency}">
    <title>How much do you spend on the following items:</title>
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</number>

res_ex1.png

The dollar sign ($) works great for surveys fielded in the US, but what if this survey is also fielded in the UK? Fortunately, the translation system will detect the resource tag containing the currency and enable the translation team to properly translate the dollar sign into the euro (€).

There are several components of the survey that cannot be detected by the translation system (e.g. attributes such as ss:postText, Python code, XML styles, etc..). It is best practice to use <res> tags for strings that outside of your typical survey elements.

1: Utilizing a Resource Tag in a Survey

You can pipe a resource tag into a survey using the following syntax:

[res resname]

where resname is the label of the resource tag.

If you have a resource tag embedded inside a question, use the following syntax:

[res Q1,resname]

Where Q1 is the question label and resname is the label of the resource tag.

If the resource tag is embedded inside a question which is inside a Loop, you can pipe the resource tag into a survey using the following syntax:

[res Q1_[loopvar: label],resname]

If the resource tag is inside a Loop but not embedded inside a question, you would need to use the following syntax:

[res Q1_[loopvar: label],resname_[loopvar: label]]

2: Error Messages

<res> tags should be used for error messages. Consider the following example:

<res label="odd_number_error">Please enter an odd number. (You entered %d)</res>
<number label="Q1" size="3" optional="0" title="Enter an odd number below:">
  <validate>
if not this.ival % 2:
    error(res.odd_number_error % this.ival)
  </validate>
</number>

res_ex2.png

3: Overriding System Messages

All of the default error messages shown by the survey system can be overridden using <res> tags.

For example, we can globally override the default error message when a value has not been supplied for a <radio> question:

<res label="sys_noAnswerSelected">Please reread the text and choose the appropriate response.</res>
<radio label="Q1" optional="0" title="Please choose one.">
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</radio>

res_ex3.png

Notice the special syntax we used in the code above. To override a system error message, we must prefix the message name with "sys_".

You may also override system error messages globally and differently for specific questions. Consider the following example:

<res label="sys_noAnswerSelected">Please reread the text and choose the appropriate response.</res>
<radio label="Q1" optional="0" title="Please choose one.">
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</radio>

<radio label="Q2" optional="0" title="Please choose one.">
    <res label="sys_noAnswerSelected">You must choose an item here.</res>
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</radio>

res_ex4.png

View the System Language Resources document for more information on the error messages available.

4: Combining With Pipes

Resource tags can be combined with <pipe> tags to present dynamic content. First, consider the following example without a <res> tag:

<pipe label="Main_Concept">
  <case label="c1" cond="hasMarker('c1')"><img src="[rel concept_1.png]"/></case>
  <case label="c2" cond="hasMarker('c2')"><img src="[rel concept_2.png]"/></case>
  <case label="c3" cond="hasMarker('c3')"><img src="[rel concept_3.png]"/></case>
  <case label="c4" cond="1">Bad pipe</case>
</pipe>

<html label="Concept_Show" where="survey">
  <p>Please view the following concept. You will be asked additional questions on the next page.</p>
  <p>[pipe: Main_Concept]</p>
</html>

In this example, we are simply showing a concept image based on the marker they were assigned.

We can improve the code slightly by using a <res> to store the main content and piping in the parts that change only. This not only produces cleaner code, but it also will save time in the future if adjustments need to be made. Here's the same example with a <res> tag:

<res label="Concept_Image"><img src="[rel concept_%s.png]"/></res>

<pipe label="Main_Concept">
  <case label="c1" cond="hasMarker('c1')">1</case>
  <case label="c2" cond="hasMarker('c2')">2</case>
  <case label="c3" cond="hasMarker('c3')">3</case>
  <case label="c4" cond="1">Bad pipe</case>
</pipe>

<html label="Concept_Show" where="survey">
  <p>Please view the following concept. You will be asked additional questions on the next page.</p>
  <p>${res.Concept_Image % pipe.Main_Concept}</p>
</html>

A more complex example would entail a concept that consists of a large amount of text with only a few parts that change. If we combine <res> and <pipe> tags together, our code and concept text will be easier to read and easier to change. Consider this concept presented by an internet service provider:

<res label="ISP_Concept_Text">
  <p>For a limited time, our brand is offering an exclusive deal to you, our %s customers.</p>
  <p>Have you heard about the latest accusations in regards to your data? Here's a short list of things going on:</p>
  <ul>
      %s
  </ul>
  <p>When you sign up for our internet at the low rate of %s per month, all of those things will still happen but we'll throw in a 50" TV when you sign up before November!</p>
</res>

<pipe label="Concept_Customers">
  <case label="c1" cond="Q3.r1">Super Duper Co.</case>
  <case label="c2" cond="Q3.r2">Agile Dojo</case>
  <case label="c3" cond="Q3.r3">Mountain Monster</case>
  <case label="c4" cond="1">bad pipe</case>
</pipe>

<pipe label="Concept_ISPActivities">
  <case label="c1" cond="hasMarker('c1')"><![CDATA[
      <li>Your data is sold to 3rd party vendors</li>
      <li>Your online activities are being watched</li>
      <li>Your online identity is at risk</li>
  ]]></case>
  <case label="c2" cond="hasMarker('c2')"><![CDATA[
      <li>Your data may be sold to 3rd party vendors</li>
      <li>Your online activities may be actively watched</li>
      <li>Your online identity may be at risk</li>
      <li>The Matrix may have you!</li>
      ]]></case>
  <case label="c3" cond="hasMarker('c3')"><![CDATA[
      <li>Your data <span style="background: black;">may be sold to 3rd</span> party <span style="background: black;">vendors</span></li>
      <li>Your online activities may be active<span style="background: black;">ly watched</span></li>
      <li>Your online <span style="background: black;">identity may be at risk</span></li>
      <li><span style="background: black;">The Matrix may have</span> you!</li>
      ]]></case>
  <case label="c4" cond="1">bad pipe</case>
</pipe>

<pipe label="Concept_PricePoint">
  <case label="c1" cond="hasMarker('c1')">$50</case>
  <case label="c2" cond="hasMarker('c2')">$75</case>
  <case label="c3" cond="hasMarker('c3')">$95</case>
  <case label="c4" cond="1">bad pipe</case>
</pipe>

<html label="Show_Concept" where="survey">
    ${res.ISP_Concept_Text % (pipe.Concept_Customers, pipe.Concept_ISPActivities, pipe.Concept_PricePoint)}
</html>

res_lol.png

Learn more: Pipe Tag

In the examples above, we performed several string operations using Python's "%" syntax. Consider learning about Python's built-in function, Format.

5: Restricting by Language

It is also possible to restrict resources by language. To restrict the languages a resource will be used in, add the mls attribute to the resource tag, specifying the desired language(s).

For example, if you would like to restrict the "$" resource in a spend question to English only, you would add mls="english" to the resource tag for that element:

<res mls="english" label="currency">$</res>

<number label="Q1" size="4" verify="range(0, 9999)" ss:preText="${res.currency}">
    <title>How much do you spend on the following items:</title>
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</number>

Likewise, the example below would restrict the translation of sys_noAnswerSelected to custom text for French and use the default sys_noAnswerSelected text for other languages:

<res label="sys_noAnswerSelected" mls="french">select only one</res>

Restricted resources will still be displayed in the Language Manager for all survey languages (not counted as "missing"), but will be excluded from the language translation files.

6: Reviewing Resource Tags 

Once resource tags have been added to a survey, they can be reviewed at any time from the Survey Editor. To view any resource tags you have added to your survey, select "Open Resource Tags" in the Actions menu: 

2016-04-20_18-30-05.png

If a survey does not contain any resource tags, this option will not be available (i.e., it will not be clickable).

Any existing resource tags will appear in a popup window, along with the label and text for each:

2016-04-21_11-16-55.png

When you are done reviewing your resource tags, click "Close" to return to the staging area in the Survey Editor.

  • War dieser Artikel hilfreich?