String Resource¶
XML file saved at:
res/
string/
strings.xml
strings-fr.xml
strings-en.xml
strings-en-US.xml
Syntax¶
<?xml version="1.0" encoding="utf-8"?>
<strings>
<string name="myString">My String value</string>
</strings>
Resource reference¶
XML
:@string/string_name
Java
:Res.string.string_name
Example¶
XML file saved at res/values/strings.xml
:
<?xml version="1.0" encoding="utf-8"?>
<strings>
<string name="myString">My String value</string>
</strings>
This layout XML applies a string to a View
:
<Button text="@string/myString" />
This application code retrieves a string:
String myString = ResManager.getString(Res.string.myString);
Formatting¶
Sometimes it can be useful to inject values in a localized string. This is possible with formatting:
<string name="greetings">Hello, %s!</string>
In this example, the string resource has only one format specifier: %s which represents the string format specifier. You can format the string with arguments from your application like this:
String text = ResManager.getString(Res.string.greetings, username);
The number of format specifiers and arguments must be the same. The format rules are the same as for java.util.Formatter
, as detailed here: http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Formatter.html
If a string resource contains format specifiers but ResManager.getString(int, Object...)
is called with no arguments, the format specifiers are considered as literal characters, and no formatting is applied.
Note
If formatting is used but the percent ‘%
’ literal character needs to be displayed, it must be doubled: ‘%%
’.
Special characters¶
As string resources are contained in an XML file, some special characters need to be handled differently:
- quote (
'
) -> ' - double-quotes (
"
) -> " - less than (
<
) -> < - greater than (
>
) -> > - ampersand (
&
) -> &
If these characters need to appear in a string resource, the escaped version needs to be used, as in:
<string name="greetings">Salut l'artiste!</string>
Encoding¶
The only supported encoding for XML string resource files is UTF-8.
Migrating From NeoMAD 3.X¶
In NeoMAD 3.X texts were contained in a CSV file and declared using the <strings>
element in the URS
file.
Here is an example of the declaration of a CSV file in the URS file:
<strings path="strings/strings.csv" />
From the 4.0 version and for backward compatibility, NeoMAD will automatically convert this legacy CSV file into the new resource organization.
The res/string
folder will be created during the build process, and filled with XML files containing the strings that were present in the CSV.
Note
After the conversion has been made, a message is displayed in the console, warning that the CSV file is now ignored. To avoid this warning for the next build, remove XML line <strings .... />
from the URS
file.