【翻译】(38)字符串资源

【翻译】(38)字符串资源

 

see

http://developer.android.com/guide/topics/resources/string-resource.html

 

原文见

http://developer.android.com/guide/topics/resources/string-resource.html

 

-------------------------------

 

String Resources

 

字符串资源

 

A string resource provides text strings for your application with optional text styling and formatting. There are three types of resources that can provide your application with strings:

 

一个字符串资源为你的应用程序提供文本字符串，带有可选的文本样式化和格式化。你可以用字符串向你的应用程序提供三种类型的资源：

 

* String

 

* 字符串

 

XML resource that provides a single string.

 

提供单一字符串的XML资源。

 

* String Array

 

* 字符串数组

 

XML resource that provides an array of strings.

 

提供一个字符串数组的XML资源。

 

* Quantity Strings (Plurals)

 

* 数量字符串（复数）

 

XML resource that carries different strings for different quantities of the same word or phrase.

 

携带相同单词或短语在不同数量下的不同字符串的XML资源。

 

All strings are capable of applying some styling markup and formatting arguments. For information about styling and formatting strings, see the section about Formatting and Styling.

 

所有字符串有能力应用一些样式化标记和格式化参数。想获取关于样式化和格式化字符串的信息，请参见关于格式化和样式化的章节。

 

-------------------------------

 

String

 

字符串

 

A single string that can be referenced from the application or from other resource files (such as an XML layout).

 

一个单一字符串，它可以从应用程序中或从其它资源文件中引用（诸如一个XML布局）。

 

-------------------------------

 

Note: A string is a simple resource that is referenced using the value provided in the name attribute (not the name of the XML file). So, you can combine string resources with other simple resources in the one XML file, under one <resources> element.

 

注意：一个字符串式一个简单资源，它使用在name属性中提供的值来引用（而非XML文件的名称）。所以，你可以在一个XML文件中把字符串资源和其它简单资源合并在一起，放在<resources>元素下。

 

-------------------------------

 

* file location:

 

* 文件位置：

 

res/values/filename.xml

 

res/values/<文件名>.xml

 

The filename is arbitrary. The <string> element's name will be used as the resource ID.

 

文件名是任意的。<string>元素的名称将被用作资源ID。

 

* compiled resource datatype:

 

* 被编译的资源数据类型：

 

Resource pointer to a String.

 

指向一个String的资源指针。

 

* resource reference:

 

* 资源引用：

 

In Java: R.string.string_name

 

在Java中：R.string.<字符串名称>

 

In XML:@string/string_name

 

在XML中：@string/<字符串名称>

 

* syntax:

 

* 语法：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string

        name="string_name"

        >text_string</string>

</resources>

 

-------------------------------

 

* elements:

 

* 元素：

 

* <resources>

 

Required. This must be the root node.

 

必需的。它必须是根节点。

 

No attributes.

 

没有属性。

 

* <string>

 

A string, which can include styling tags. Beware that you must escape apostrophes and quotation marks. For more information about how to properly style and format your strings see Formatting and Styling, below.

 

一个字符串，它可以包含样式化标志。请意识到你必须转义单引号和双引号。想获取关于如何正确地样式化和格式化你的字符串的更多信息，请参见下面的格式化和样式化章节。

 

* attributes:

 

* 属性：

 

* name

 

* 名称

 

String. A name for the string. This name will be used as the resource ID.

 

字符串。字符串的名称。这个名称将被用作资源ID。

 

* example:

 

* 示例：

 

XML file saved at res/values/strings.xml:

 

保存为res/values/strings.xml的XML文件：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string name="hello">Hello!</string>

</resources>

 

-------------------------------

 

This layout XML applies a string to a View:

 

这个布局XML应用一个字符串到一个View：

 

-------------------------------

 

<TextView

    android:layout_width="fill_parent"

    android:layout_height="wrap_content"

    android:text="@string/hello" />

 

-------------------------------

 

This application code retrieves a string:

 

这段应用程序代码接收一个字符串：

 

-------------------------------

 

String string = getString(R.string.hello);

 

-------------------------------

 

You can use either getString(int) or getText(int) to retrieve a string. getText(int) will retain any rich text styling applied to the string.

 

你可以使用getString(int)或getText(int)去取出一个字符串。getText(int)将保留应用在字符串上的任意富文本样式。

 

-------------------------------

 

String Array

 

字符串数组

 

An array of strings that can be referenced from the application.

 

一个字符串数组，它可以被应用程序引用。

 

-------------------------------

 

Note: A string array is a simple resource that is referenced using the value provided in the name attribute (not the name of the XML file). As such, you can combine string array resources with other simple resources in the one XML file, under one <resources> element.

 

注意：一个字符串数组是一个简单资源，它使用在name属性中提供的值来引用（而非XML文件的名称）。所以，你可以在一个XML文件中把字符串数组资源和其它简单资源合并在一起，放在<resources>元素下。

 

-------------------------------

 

* file location:

 

* 文件位置：

 

res/values/filename.xml

 

res/values/<文件名>.xml

 

The filename is arbitrary. The <string-array> element's name will be used as the resource ID.

 

文件名是任意的。<string-array>元素的名称将被用作资源ID。

 

* compiled resource datatype:

 

* 被编译的资源数据类型：

 

Resource pointer to an array of Strings.

 

指向一个String数组的资源指针。

 

* resource reference:

 

* 资源引用：

 

In Java: R.array.string_array_name

 

在Java中：R.array.<字符串数组名称>

 

* syntax:

 

* 语法：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string-array

        name="string_array_name">

        <item

            >text_string</item>

    </string-array>

</resources>

 

-------------------------------

 

* elements:

 

* 元素：

 

* <resources>

 

Required. This must be the root node.

 

必需的。它必需是根节点。

 

No attributes.

 

无属性。

 

* <string-array>

 

Defines an array of strings. Contains one or more <item> elements.

 

定义一个字符串数组。包含一个或多个<item>元素。

 

* attributes:

 

* 属性：

 

* name

 

String. A name for the array. This name will be used as the resource ID to reference the array.

 

字符串。数组的名称。这个名称将被用作资源ID以引用这个数组。

 

* <item>

 

A string, which can include styling tags. The value can be a referenced to another string resource. Must be a child of a <string-array> element. Beware that you must escape apostrophes and quotation marks. See Formatting and Styling, below, for information about to properly style and format your strings.

 

一个字符串，它可以包含样式化标志。该值可以是一个指向另一个字符串资源的引用。必须是<string-array>元素的子元素。请意识到你必须转义单引号和双引号。参见下面的格式化和样式化章节，以获取关于正确地样式化和格式化你的字符串的信息。

 

No attributes.

 

无属性。

 

* example:

 

* 示例

 

XML file saved at res/values/strings.xml:

 

保存为res/values/strings.xml的XML文件：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string-array name="planets_array">

        <item>Mercury</item>

        <item>Venus</item>

        <item>Earth</item>

        <item>Mars</item>

    </string-array>

</resources>

 

-------------------------------

 

This application code retrieves a string array:

 

这段应用程序代码取出一个字符串数组：

 

-------------------------------

 

Resources res = getResources();

String[] planets = res.getStringArray(R.array.planets_array);

 

-------------------------------

 

-------------------------------

 

Quantity Strings (Plurals)

 

数量字符串（复数）

 

Different languages have different rules for grammatical agreement with quantity. In English, for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd write "n books". This distinction between singular and plural is very common, but other languages make finer distinctions. The full set supported by Android is zero, one, two, few, many, and other.

 

不同的语言对数量的语法协议有不同的规则。例如，在英语中，数量1是特殊例子。我们书写“一本书”，但对于其它任意数量，我们写作“n本书的复数”。这个在单数和复数之间的区别是非常普遍的，但其它语言会作出更大的区别。Android支持的完全集合有0，1，2，少量，许多，以及其它。

 

The rules for deciding which case to use for a given language and quantity can be very complex, so Android provides you with methods such as getQuantityString() to select the appropriate resource for you.

 

对于一个给定的语言来说决定使用哪种情况的规则以及数量可能非常复杂，所以Android向你提供方法诸如getQuantityString()以为你选择合适的资源。

 

Note that the selection is made based on grammatical necessity. A string for zero in English will be ignored even if the quantity is 0, because 0 isn't grammatically different from 2, or any other number except 1 ("zero books", "one book", "two books", and so on). Don't be misled either by the fact that, say, two sounds like it could only apply to the quantity 2: a language may require that 2, 12, 102 (and so on) are all treated like one another but differently to other quantities. Rely on your translator to know what distinctions their language actually insists upon.

 

注意作出选择是基于语法的必要性。在英语中用于0的字符串将被忽略，即便数量为0，因为0在语法上和2，或者其它任意不是1的数没有区别（“0本书的复数”，“一本书的单数”，“两本书的复数”，如此类推）。不要被这样的事实迷惑，2听起来好像只应该应用在数量2上：一种语言可能需要2，12，102（如此类推）全都像另一种情况但不同于其它数量来对待。依靠你的翻译员来知道他们的语言实际上坚持要求什么区别。

 

It's often possible to avoid quantity strings by using quantity-neutral formulations such as "Books: 1". This will make your life and your translators' lives easier, if it's a style that's in keeping with your application.

 

通常可以通过使用数量中性的公式诸如“书本数：1”来避免数量字符串。这将使你的生活和你的翻译员的生活好过些，如果这是一种坚持保留在你的应用程序中风格。

 

-------------------------------

 

Note: A plurals collection is a simple resource that is referenced using the value provided in the name attribute (not the name of the XML file). As such, you can combine plurals resources with other simple resources in the one XML file, under one <resources> element.

 

注意：一个复数集合是一个简单资源，它使用name属性中提供的值来引用（而非XML文件的名称）。因此，你可以组合复数资源和其它简单资源在一个XML文件中，放在一个<resources>元素下。

 

-------------------------------

 

* file location:

 

* 文件位置：

 

res/values/filename.xml

 

res/values/<文件名>.xml

 

The filename is arbitrary. The <plurals> element's name will be used as the resource ID.

 

文件名是任意的。<plurals>元素的名称将被用作资源ID。

 

* resource reference:

 

* 资源引用：

 

In Java: R.plurals.plural_name

 

在Java中：R.plurals.<复数名称>

 

* syntax:

 

* 语法：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <plurals

        name="plural_name">

        <item

            quantity=["zero" | "one" | "two" | "few" | "many" | "other"]

            >text_string</item>

    </plurals>

</resources>

 

-------------------------------

 

* elements:

 

* 元素：

 

* <resources>

 

Required. This must be the root node.

 

必需的。它必须是根节点。

 

No attributes.

 

无属性。

 

* <plurals>

 

A collection of strings, of which, one string is provided depending on the amount of something. Contains one or more <item> elements.

 

一组字符串，其中一个字符串被提供，依赖于东西的数量。包含一个或多个<item>元素。

 

* attributes:

 

* 属性：

 

* name

 

String. A name for the pair of strings. This name will be used as the resource ID.

 

字符串。字符串对的名称。这个名称将被用作资源ID。

 

* <item>

 

A plural or singular string. The value can be a referenced to another string resource. Must be a child of a <plurals> element. Beware that you must escape apostrophes and quotation marks. See Formatting and Styling, below, for information about to properly style and format your strings.

 

一个复数或单数字符串。值可能是一个指向另一个字符串资源的引用。必须是一个<plurals>元素的子元素之一。请意识到你必须转义单引号和双引号。参见下面的格式化和样式化章节，以获取关于正确地样式化和格式化你的字符串的信息。

 

* attributes:

 

* 属性：

 

* quantity

 

Keyword. A value indicating when this string should be used. Valid values, with non-exhaustive examples in parentheses:

 

关键词。一个值指示这个字符串应该在什么时候被使用。可用的值，括号中带有不可穷尽示例：

 

-------------------------------

 

* Value Description

 

* 值 描述

 

* zero When the language requires special treatment of the number 0 (as in Arabic).

 

* zero 当语言需要数字0的特殊对待时（当使用阿拉伯语时）。

 

* one When the language requires special treatment of numbers like one (as with the number 1 in English and most other languages; in Russian, any number ending in 1 but not ending in 11 is in this class).

 

* one 当语言需要像1那样的数的特殊对待时（当使用英语中的数1和其它大多数语言时；在俄语中，任何以1结束的数但不是以11结束的数在这个类别中）。

 

* two When the language requires special treatment of numbers like two (as in Welsh).

 

* two 当语言需要像2那样的数的特殊对待时（当使用威尔士语时）

 

* few When the language requires special treatment of "small" numbers (as with 2, 3, and 4 in Czech; or numbers ending 2, 3, or 4 but not 12, 13, or 14 in Polish).

 

* few 当语言需要“小”数量的特殊对待时（当在捷克语中使用2、3、4；或在波兰语中使用以2，3或4结束但不是12，13或14的数时）。

 

* many When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).

 

* many 当语言需要“大”数量的特殊对待时（当在马耳他语中使用11-99结束的数字时）

 

* other When the language does not require special treatment of the given quantity.

 

* other 当语言不需要所给数量的特殊对待时。

 

-------------------------------

 

* example:

 

* 示例：

 

XML file saved at res/values/strings.xml:

 

保存为res/values/strings.xml的XML文件：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <plurals name="numberOfSongsAvailable">

        <item quantity="one">One song found.</item>

        <item quantity="other">%d songs found.</item>

    </plurals>

</resources>

 

-------------------------------

 

XML file saved at res/values-pl/strings.xml:

 

保存为res/values-pl/strings.xml的XML文件：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <plurals name="numberOfSongsAvailable">

        <item quantity="one">Znaleziono jedn? piosenk?.</item>

        <item quantity="few">Znaleziono %d piosenki.</item>

        <item quantity="other">Znaleziono %d piosenek.</item>

    </plurals>

</resources>

 

-------------------------------

 

Java code:

 

Java代码：

 

-------------------------------

 

int count = getNumberOfsongsAvailable();

Resources res = getResources();

String songsFound = res.getQuantityString(R.plurals.numberOfSongsAvailable, count, count);

 

-------------------------------

 

When using the getQuantityString() method, you need to pass the count twice if your string includes string formatting with a number. For example, for the string %d songs found, the first count parameter selects the appropriate plural string and the second count parameter is inserted into the %d placeholder. If your plural strings do not include string formatting, you don't need to pass the third parameter to getQuantityString.

 

当使用getQuantityString()方法时，你需要两次传递count，如果你的字符串包含用一个数格式化的字符串。例如，对于字符串“找到%d首歌曲”，第一个count参数选择合适的复数字符串，而第二个count参数被插入进%d占位符。如果你的复数字符串不包含字符串格式化，那么你不需要传递第三参数给getQuantityString。

 

-------------------------------

 

Formatting and Styling

 

格式化和样式化

 

Here are a few important things you should know about how to properly format and style your string resources.

 

这里有一些你应该知道的重要事项，关于如何合理地格式化和样式化你的字符串资源。

 

Escaping apostrophes and quotes

 

转义单引号和双引号

 

If you have an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other type of enclosing quotes. For example, here are some stings that do and don't work:

 

如果你在你的字符串中有一个单引号或双引号，你必须转义它或闭合整个字符串在其它类型的闭合引号中。例如，这里有一些可以工作和不能工作的字符串（注：stings貌似笔误）（注：下面的英文内容提示其正确性，其中前两个是可工作的）：

 

-------------------------------

 

<string name="good_example">"This'll work"</string>

<string name="good_example_2">This\'ll also work</string>

<string name="bad_example">This doesn't work</string>

<string name="bad_example_2">XML encodings don&apos;t work</string>

 

-------------------------------

 

Formatting strings

 

格式化字符串

 

If you need to format your strings using String.format(String, Object...), then you can do so by putting your format arguments in the string resource. For example, with the following resource:

 

如果你需要使用String.format(String, Object...)格式化你的字符串，那么你可以通过把你的格式化参数放置在字符串资源中来做到这点。例如，使用以下资源：

 

-------------------------------

 

<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>

 

-------------------------------

 

In this example, the format string has two arguments: %1$s is a string and %2$d is a decimal number. You can format the string with arguments from your application like this:

 

在这个示例，格式化字符串有两个参数：%1$s是一个字符串而%2$d是一个十进制数。你可以用来自你的应用程序的参数来格式化字符串，就像这样：

 

-------------------------------

 

Resources res = getResources();

String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);

 

-------------------------------

 

Styling with HTML markup

 

用HTML标记样式化

 

You can add styling to your strings with HTML markup. For example:

 

你可以使用HTML标记添加样式到你的字符串。例如：

 

-------------------------------

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string name="welcome">Welcome to <b>Android</b>!</string>

</resources>

 

-------------------------------

 

Supported HTML elements include:

 

支持的HTML元素包括：

 

* <b> for bold text.

 

* <b>用于黑体文本。

 

* <i> for italic text.

 

* <i>用于斜体文本。

 

* <u> for underline text.

 

* <u>用于下划线文本。

 

Sometimes you may want to create a styled text resource that is also used as a format string. Normally, this won't work because the String.format(String, Object...) method will strip all the style information from the string. The work-around to this is to write the HTML tags with escaped entities, which are then recovered with fromHtml(String), after the formatting takes place. For example:

 

有时你可能希望创建一个还被用作格式化字符串的样式化文本资源，通常，它将不能工作，因为String.format(String, Object...)方法将从字符串中去除所有样式化信息。对此，权宜之计是用转义的实体书写HTML标签，然后用fromHtml(String)恢复它们，在格式化发生后。例如：

 

1. Store your styled text resource as an HTML-escaped string:

 

1. 保存你的样式化文本资源作为一个HTML转义字符串：

 

-------------------------------

 

<resources>

  <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>

</resources>

 

-------------------------------

 

In this formatted string, a <b> element is added. Notice that the opening bracket is HTML-escaped, using the &lt; notation.

 

在这个格式化字符串中，添加了一个<b>元素。注意左尖括号是HTML转义的，使用&lt;记号。

 

2. Then format the string as usual, but also call fromHtml(String) to convert the HTML text into styled text:

 

2. 然后像通常那样格式化字符串，但同时调用fromHtml(String)以转换HTML文本为样式化字符串：

 

-------------------------------

 

Resources res = getResources();

String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);

CharSequence styledText = Html.fromHtml(text);

 

-------------------------------

 

Because the fromHtml(String) method will format all HTML entities, be sure to escape any possible HTML characters in the strings you use with the formatted text, using htmlEncode(String). For instance, if you'll be passing a string argument to String.format() that may contain characters such as "<" or "&", then they must be escaped before formatting, so that when the formatted string is passed through fromHtml(String), the characters come out the way they were originally written. For example:

 

因为fromHtml(String)方法将格式化所有HTML实体（注：HTML实体是指HTML转义符，格式为&entity_name;，又称为字符实体），以确保转义你用于格式化字符串的字符串中任意可能的HTML字符，使用htmlEncode(String)。例如，如果你正要传递一个字符串参数给String.format()，它可能包含诸如"<"或"&"的字符串，那么它们必须在格式化之前被转义，致使当格式化字符串被传递通过fromHtml(String)时，字符以它们原来被书写的方式显示出来。例如：

 

-------------------------------

 

String escapedUsername = TextUtil.htmlEncode(username);

 

Resources res = getResources();

String text = String.format(res.getString(R.string.welcome_messages), escapedUsername, mailCount);

CharSequence styledText = Html.fromHtml(text);

 

-------------------------------

 

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

 

除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。

 

Android 4.0 r1 - 18 Jan 2012 22:14

 

-------------------------------

 

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

 

（此页部分内容基于Android开源项目，以及使用根据创作公共2.5来源许可证描述的条款进行修改）

 

（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：

* ソフトウェア技術ドキュメントを勝手に翻訳

http://www.techdoctranslator.com/android

* Ley's Blog

http://leybreeze.com/blog/

* 农民伯伯

http://www.cnblogs.com/over140/

* Android中文翻译组

http://androidbox.sinaapp.com/

）