Issue 5068 - Define translation string format

translation-string-format.md

Index: translation-string-format.md
===================================================================
new file mode 100644
--- /dev/null
+++ b/translation-string-format.md
@@ -0,0 +1,67 @@
+# Translation string format

[saroyanm, 2017/06/01 12:07:25]

I think it makes sense to define if this document applies to Website or to the
UI module as well...

We can define that this applies to the Website and extend for UI and or update
to it if it will make sense.. 

Anyway for the stringID decisins for UI module we will need Thomas as well. 

I'll review this considering practices we used/started to use across websites
module.

[juliandoucette, 2017/06/07 16:07:39]

Acknowledged.

I don't know how translations are done in the extension. Do strings have the
same parts?

[ire, 2017/06/08 11:18:34]

It would be really helpful to include some examples in this document. We can
have a sample page that shows how the translation strings are used in different
contexts, e.g. a heading, paragraph, several list items, etc. 

[juliandoucette, 2017/06/08 21:07:51]

Acknowledged.

[Lisa, 2017/06/09 14:14:47]

Totally agree with Ire. 

[saroyanm, 2017/06/13 09:48:27]

Yes, I also agree with you.

Suggestion: I think examples shouldn't block launching the initial version with
"hard rules. I suggest adding only examples that are crucial for this version of
the document and add more in future to make the document more visual with the
examples. 

[saroyanm, 2017/06/13 09:48:27]

I think strings are very similar to what we have, it's more in between of "Think
meaningful stringID to reflect the meaning of the string" and reflecting
location, for examples in the tabs or sections. So they are very close to this
one. I don't see an issue adopting this practice in the UI as well.
Anyway websites contains way more strings than the UI, so having automation in
Websites currently is more crucial rather than in shared UI.
Adopting final version completely or partially in ABP shared UI will require
@Thomas final go as well.
My suggestion: let's meet requirements of websites module and adopt in UI later.
I don't want to block current state with additional layer.

Suggestion: Add @Thomas as a CC to current review here.

+
+`{{identifier[context] content }}`
+
+## Brackets

[saroyanm, 2017/06/01 12:07:25]

Suggestion: I think "required" can go right next to heading.

[juliandoucette, 2017/06/07 16:07:39]

Acknowledged.

Good point.

+
+Two curly braces must (required) go at the beginning and end of a translated string in Markdown and HTML format.

[saroyanm, 2017/06/01 12:07:26]

Suggestion: I think from "must" it's obvious that it's required.
We can omit "(required)"

[juliandoucette, 2017/06/07 16:07:39]

Acknowledged.

I guess I thought this made it more formal :D - I'll remove unless someone else
objects.

[ire, 2017/06/08 11:18:34]

I think, as Manvel suggested later in this doc, that the "required" should go in
brackets next to the heading, i.e. `## Brackets (required)`. I think it is
useful to have the word required there, even though it says "must", but I agree
that having it right after the word "must" seems like a duplicate. 

[juliandoucette, 2017/06/08 21:07:51]

Acknowledged.

+
+## Identifier
+
+An identifier must (required) immediately follow two opening brackets.
+
+- An identifier may identify only one string on one page

[saroyanm, 2017/06/01 12:07:26]

Word "may" sound "balanced" for me, let me know if I'm wrong.. I think this
should be more strong, like "should".

[juliandoucette, 2017/06/07 16:07:39]

"may" means *can*. "should" means *preferably*. "should" is not right because an
identifier can **only** (not *preferably*) identify one string on one page. That
being said, perhaps "can" is more direct and less *balanced* than "may"? I don't
have a strong opinion.

[saroyanm, 2017/06/13 09:48:27]

In this context I understand wording this way:
* May, can - expressing possibility
* Should, must - expressing obligation

In this case I was suggesting to express obligation, so people will not use same
identifier for different strings.

+- If one string occurs more than once on one page in the same context, the same identifier may be used and the string context and content may be omitted
+- An identifier may contain only lowercase latin letters and dashes

[saroyanm, 2017/06/01 12:07:26]

Suggestion: We can make this more strong. "should" instead of "may". 
Note: each time we use may it will require content creator to think twice what
to use. In case of previous point I can see why you are using "balanced" word
though.

[juliandoucette, 2017/06/07 16:07:38]

See comment above.

[saroyanm, 2017/06/13 09:48:28]

same as the comment above.

+
+### Identifier format
+
+`summary-context-number`
+
+**Summary**
+:   An identifier summary should describe the contents of the string or it’s parent heading in as few words as possible.

[saroyanm, 2017/06/01 12:07:26]

Note: and example here I think could make things bit more clear, but I think we
can revisit the example and find wording that will make this point more
describing later on.. Separate review. let's first finalize this version.

[juliandoucette, 2017/06/07 16:07:39]

Acknowledged.

[Lisa, 2017/06/09 14:14:47]

We should include an example. Personally, I'd like us all to use the same format
(because I'm anal like that), so we all know what to do and how to do it. Plus,
I think it just looks cleaner.

Nitpick: 'it's' should be 'its'

[juliandoucette, 2017/06/09 15:13:54]

You just taught me something :)

+
+**Context**
+:   An identifier context should describe context in which the string appears in HTML. e.g. {h: heading, p: paragraph, li: list item}

[juliandoucette, 2017/05/18 08:54:37]

Note: We have had a policy about spelling things out e.g. "paragraph" instead of
"p". I'm not sure if we can/should break this rule.

[saroyanm, 2017/06/01 12:07:25]

I think if we agree with this approach this can be an exception, because here
you are using the HTML element intentionally to make it easy searchable, rather
than shortening to save space.

Though it will require changing the string name if you will change the HTML
element, which might lead to lose of the translation, for example if we start
generating them on the fly..

So here are two extremes:
* Think meaningful stringID to reflect the meaning of the string
  Cons: Hard to autogenerate
  Pros: Not required to update stringID if Semantic changes.
* Use HTML reference, to make it autogeneratable
  Cons: We might loose the translations if the HTML element is changed
  Pros: We can auto-generate, improve the speed.

Me personally don't have strong opinion about which to choose though I lean
towards later one (I see that both solution are not ideal), but we still need to
keep that in mind and ideally find solution, because I imagine this can become
tricky issue, if the layout or semantics changes. If you have anything on your
mind between this both extremes let me know.

[juliandoucette, 2017/06/07 16:07:39]

Good point. I think there is a middle ground here. I think that text in a
heading or on a button may be translated differently than the same text alone in
a paragraph. Therefore, I think there is a place for *context* in string IDs. I
think the middle ground is less specific than an exact HTML tag and more
specific than [heading, paragraph, button-label, list-item]. 

I will wait for your feedback before digging into this deeper.

[juliandoucette, 2017/06/07 16:16:18]

I'm afraid this was unclear. What I mean is that there are probably contexts
which are relevant for several types of HTML elements. And that we can probably
determine what these contexts are. [heading, body, label, item] may be a good
start.

[saroyanm, 2017/06/13 09:48:28]

I agree with you. Would be great to come up with the list of exceptions and best
with the examples as well. Having Heading, menu items and Button labels as a
start for the exception can be good start I think.

+
+**Number**
+:   A number should uniquely identify an identifier among other similar identifiers. e.g. among multiple consecutive list items or paragraphs with the same identifier summary and context.

[juliandoucette, 2017/05/18 08:54:37]

Note: A number is not necessary if there are not more than one of the same
identifier.

[saroyanm, 2017/06/01 12:07:25]

Having number "required" will minimize the effort of automation. If this is the
final goal.

[juliandoucette, 2017/06/07 16:07:38]

I agree.

I found it awkward to use and/or not use this number in practice.

+
+## Context

[saroyanm, 2017/06/01 12:07:25]

Suggestion: Let's mark optional here rather than in the description, if you want
to emphasis that context in general is optional for people who will read this
rather than the "Readme" of the CMS.

[juliandoucette, 2017/06/07 16:07:39]

Acknowledged.

+
+A Context should (optional) immediately follow an identifier.
+
+- Context must be enclosed within square brackets
+- Context may contain upper and lower case latin letters, dashes, commas, apostrophes, and spaces
+
+### Context format
+
+A Context should (optional) describe the HTML context (e.g. heading / paragraph / list item) and meaning (e.g. “Order” as in “place an order” or “Order” as in “Order of events”) of the string contents.
+
+## Content
+
+- A string’s content must (required) be separated from its identifier and context by one space
+- A string’s content should (optionally) be separated from it’s closing braces by one space

[saroyanm, 2017/06/01 12:07:26]

Doesn't it mean that space should also being applied in between opening braces
and Identifier.
I mean "{{ stringId[context] string }}" rather than "{{stringId[context] string
}}" ?

[juliandoucette, 2017/06/07 16:07:39]

I didn't know that we could put a space before the stringId until Ire submitted
a pull request like this recently :D ... Now that I Think of it, I like the
first one.

[ire, 2017/06/08 11:18:34]

I also prefer the first option. But I think we should either have no spaces next
to the curly braces, or one space, i.e. "{{ stringId[context] string }}" or
"{{stringId[context] string}}". I don't think we should have no-space on one
side and a space on the other, i.e. "{{stringId[context] string }}"

[juliandoucette, 2017/06/08 21:07:51]

Acknowledged.

+- A string must not (required) contain two closing brackets
+- An English string should (optional) not contain non-ascii characters
+
+## Jinja2 format translation strings

[ire, 2017/06/08 11:18:34]

NIT: It's a bit confusing here to start talking about a different format. I
think it should be stated at the beginning of the document that there are 2
formats, and that the document covers the first format earlier. As an extra
nitty NIT, the heading levels could be reworked a bit so it's more clear. 

[juliandoucette, 2017/06/08 21:07:51]

Acknowledged.

+
+`{{ ”content” | translate(“identifier”, “context”) }}`
+
+Jinja2 (.tmpl) format strings are made up of the same parts (identifier, context, content) in a different format (Jinja2 filter format). The same rules apply to each part, except that the identifier and context must be surrounded by double quotes.
+
+## Fixed tags
+
+`<fix>text</fix>`
+
+Fixed tags may (optional) appear within string contents. They are meant to identify parts of a string that may not be translated in some languages.
+
+- Fix tags must be closed
+- A fix tag may be manually overriden by translations
+
+### Common uses

[ire, 2017/06/08 11:18:34]

Can we have a rule on whether the company name and products should always be
surrounded by a <fix>?

[juliandoucette, 2017/06/08 21:07:51]

Acknowledged.

I guess "optional" and "common uses" are a little misleading here. Fix tags are
*optional* in the sense that the code will work without them. Not *optional* in
the sense that the code will pass review without them. There are two cases where
they really come in handy:

1. When their contents may change without affecting the rest of the string
  - e.g. "We have <fix>100</fix> employees"
2. When their contents should **not** change
  - e.g. "My name should remain <fix>Julian Doucette</fix> in all languages"

[ire, 2017/06/09 06:50:11]

Yes, you're right. I was referring to the latter type of "optional".
Okay great. I think including examples like this for each of the bullet points
would help here.

+
+- numbers
+- dates
+- names (people, brands, products)

[ire, 2017/06/09 06:50:11]

Also, is there a rule on whether "eyeo", "Adblock Plus", etc, should be fixed?