Update docs for `phname`.
@@ -54,12 +54,17 @@ Here are details on how Soy generates placeholders in messages:
message might look like in the `desc` attribute and consider setting a
`phname`.
-- If you find a need to specify a placeholder name for a `print`, `call`, or
- HTML tag instead of allowing the compiler generate the default name, you can
- add the `phname` attribute. The value can either be camel case or upper
- underscore. For example, `{call .emailAddr phname="emailAddress" /}` causes
- the placeholder name to be `EMAIL_ADDRESS` instead of `XXX`. Note that
- changing a placeholder name changes the message id, causing retranslation.
+- If you find a need to specify a placeholder name for a `print`, `call`,
+ `plural`, `select` or HTML tag instead of allowing the compiler to generate
+ the default name, you can add the `phname` attribute. The value follows
+ standard variable naming conventions (must start with alphabet character,
+ and contain only alpha-numerics and underscore). By convention, it is
+ recommended that all names be UPPER_SNAKE_CASE. For historic reasons, the
+ generated placeholder name for `print`, `call`, and tag is converted to
+ UPPER_SNAKE_CASE, but not `plural` or `select`. For example, `{call
+ .emailAddr phname="emailAddress" /}` causes the placeholder name to be
+ `EMAIL_ADDRESS` instead of `XXX`. Note that changing a placeholder name
+ changes the message id, causing retranslation.
- You can set placeholder examples to aid translation. For example, `{$url
phex="www.google.com"}` or `{$name phex="Alice"}`. Placeholder examples are
@@ -204,6 +209,11 @@ written using a select statement, while `$userGender` is declared in the
{/msg}
```
+Each `select` block appears as a placeholder in the containing message. The
+placeholder name is `phname` (if present) or the UPPER_SNAKE_CASE version of the
+variable name (`TARGET_GENDER` in this example). By convention, it is
+recommended that all names be UPPER_SNAKE_CASE.
+
### Plural {#plural}
Message pluralization syntax:
@@ -218,6 +228,11 @@ Message pluralization syntax:
{/msg}
```
+Each `plural` block appears as a placeholder in the containing message. The
+placeholder name is `phname` (if present) or the UPPER_SNAKE_CASE version of the
+variable name (`NUM_DRAFTS` in this example). By convention, it is recommended
+that all names be UPPER_SNAKE_CASE.
+
WARNING: You cannot nest `plural` tags.
NOTE: If you need to use `plural` and `select` in the same message (i.e. the
