You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f2a6721
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -9,24 +9,147 @@ Review all strings that were either added or updated following Qlik documentatio
9
9
10
10
## Review Workflow
11
11
12
-
1.Analyze the content following the instructions below.
13
-
2.Identify strings added or modified in `en.json` and `en.plural.json`.
12
+
1.Identify strings added or modified in `en.json` and `en.plural.json`.
13
+
2.Analyze the content following the instructions below.
14
14
3. Apply style and clarity improvements.
15
15
4. Provide suggestions with context for translators.
16
16
17
17
## Style Guidelines
18
18
19
19
Apply these principles to all reviewed strings:
20
20
21
-
-**Language**: American English, active voice (use passive only when action is more important than subject)
22
-
-**Tone**: Simple, direct, concise. Friendly and conversational.
23
-
-**Vocabulary**: Common, everyday language for international audiences.
24
-
-**Capitalization**: Sentence case; avoid jargon.
25
-
-**Verb forms**: Present tense. Use simple forms for past/future when needed.
26
-
-**Questions**: Short forms (e.g., "Don't have an account?" not "Do you not have an account?")
27
-
-**Plurals**: Use plural forms; avoid parenthetical plurals (use "objects" not "object(s)")
28
-
-**Politeness**: Avoid "Please," "Sorry," "Thank you" in UI strings—they reduce clarity and directness.
29
-
-**Pronouns**: Use second person (you) for customers; first-person plural (we, our) for the company.
21
+
-**Language and voice**: Use American English, active voice, present tense, sentence capitalization, and serial commas. Use imperative verbs for action buttons and instructions.
22
+
-**Tone**: Be simple, direct, concise, friendly, and conversational. Use common language that an international audience understands. Avoid jargon, slang, colloquialisms, contractions, double negatives, and unnecessary politeness such as "Please," "Sorry," and "Thank you."
23
+
-**Pronouns and questions**: Address customers as "you" and refer to Qlik as "we" or "our." Use natural, short questions, such as "Do you have an account?"
24
+
-**Length**: Keep UI strings as short as possible without losing the information users or translators need.
25
+
-**Punctuation**: Use a period for complete sentences. Omit periods from labels, titles, and sentence fragments such as tooltips. Prefer two sentences to a semicolon.
26
+
-**Modifiers and articles**: Keep adjectives and adverbs close to the words they modify, use necessary articles such as "the," and remove unnecessary adjectives and adverbs.
27
+
-**Abbreviations**: Avoid abbreviations unless they are common for the intended audience, such as JSON, HTML, or PDF.
28
+
29
+
## String Structure and Localization Requirements
30
+
31
+
### Variables in strings
32
+
33
+
- Avoid variables in the middle of sentences when possible because word order differs between languages. Use punctuation to separate a variable when that makes the relationship clearer.
34
+
- Prefer: `"Cannot make public: {collectionName}"`
35
+
- Avoid: `"Cannot make {collectionName} public"`
36
+
- Explain each variable and its possible value in the string comment.
37
+
- Check whether variables affect grammatical gender or number in translation. Reword strings that require translators to infer agreement from one or more variables.
38
+
39
+
### Plural forms
40
+
41
+
- Plural strings must be stored in the repository's plural file, such as `en.plural.json` or `en_plural.json`, rather than in `en.json`.
42
+
- Use the plural schema defined by the repository. Do not use parenthetical forms.
43
+
- Preferred: separate forms such as `"one": "{{count}} file"` and `"other": "{{count}} files"`
44
+
- Avoid: `"{count} file(s)"`
45
+
- Ensure every plural form is a complete, standalone string. Languages can require more plural forms than English.
46
+
47
+
### String comments
48
+
49
+
- Require a comment that identifies the UI element, the user's task or state, and the meaning of every variable.
50
+
- State whether text is imperative or infinitive when that is ambiguous outside the product context.
51
+
- Do not add "Do not translate" tags. Translators use terminology resources to make that decision.
52
+
53
+
### Forbidden string patterns
54
+
55
+
- Do not concatenate string keys at runtime to form one sentence. Word order varies by language.
56
+
- Preferred: use one translatable string, such as `"Hello, {userName}!"`
57
+
- Avoid: combining `"Hello"`, a user name, and `"!"` at runtime.
- Preferred: keep `"Select a file to continue"` as the translatable string and apply layout outside it.
60
+
- Avoid: `"Select a file<br/>to continue"`
61
+
- Avoid incomplete phrases, dangling prepositions, and ambiguous word classes. Clarify whether a word such as "Set" is a noun or verb.
62
+
- Preferred: use a complete label, such as `"Last edited by"`, when the text is presented as a sentence or message.
63
+
- Context required: `"Edited by"` can be appropriate for a table column heading when its comment identifies the content displayed in the column.
64
+
65
+
## UI Element-Specific Guidelines
66
+
67
+
### Buttons
68
+
69
+
- Use a verb that names the specific action. Prefer "Delete," "Save changes," or "Add connection" to vague labels such as "OK," "Submit," or "Go."
70
+
71
+
### Links
72
+
73
+
- Use specific, scannable link text, such as "View documentation" or "Learn about collections." Avoid labels such as "Click here" and "More."
74
+
75
+
### Empty states
76
+
77
+
-**Title pattern**: "No \<name\> yet"
78
+
- Example: "No preparations yet"
79
+
-**Body pattern**:
80
+
- With user action: "\<Do something\> to \<get something\>. Learn more."
81
+
- Without user action: "This page lets you \<do something\>. Learn more."
82
+
- Keep instructions clear and concise
83
+
- Include call-to-action when users can take action
84
+
85
+
### Error states
86
+
87
+
-**Title pattern**: "Couldn't \<do something\>"
88
+
- Example: "Couldn't load data"
89
+
-**Body pattern**: \<cause\> + \<action to fix the problem\>
90
+
- Example: "The connection timed out. Check your network and try again."
91
+
- Tell users why there was a problem and what to do about it
92
+
- Avoid technical jargon; be conversational
93
+
94
+
### Form fields
95
+
96
+
-**Checkboxes**: Make labels parallel in grammatical structure without sacrificing clarity. For example, pair "Send email notifications" with "Show the preview panel," not "Preview panel is visible."
97
+
-**Radio buttons**: Make labels complete and clearly distinct from one another.
98
+
-**Toggle switches**: Start with a verb and describe what happens when the switch is on. For example, use "Enable automatic updates," not "Automatic updates."
99
+
-**Search fields**: Use "Search" or "Search for \<items\>"
100
+
-**Select/dropdown**: Use clear terms; order items logically
101
+
102
+
### Tooltips
103
+
104
+
- Add a tooltip only when it provides useful context that is not already visible. For example, do not add a "Save" tooltip to a button already labeled "Save."
105
+
106
+
### Stepper/wizard labels
107
+
108
+
- Use nouns (1-2 words) to label steps
109
+
- For vertical steppers: Start section titles with verbs
110
+
- Example: Step label "Engine" → Section title "Add the engine on which to process data"
111
+
- For horizontal steppers: Use short nouns only
112
+
113
+
### Tabs
114
+
115
+
- Use accurate, specific labels that describe the content in the tab. Prefer "Permissions" or "Activity log" to vague labels such as "Other" or "More."
116
+
117
+
### Tags
118
+
119
+
- Use short keywords that organize or categorize content. Avoid full sentences.
120
+
121
+
## Common Localization Pitfalls
122
+
123
+
### Generic nouns
124
+
125
+
- Avoid generic nouns such as "item" when a more specific noun is available.
126
+
- Preferred: "5 files selected" or "5 rows selected"
127
+
- Avoid: "5 items selected"
128
+
129
+
### Noun stacking/clustering
130
+
131
+
- Avoid chains of more than three nouns. Rewrite them as phrases or explain the relationship in the comment.
- Use specific terms. For example, replace "Ignore all" with "Discard all changes" or "Skip validation" as appropriate. Explain an unavoidable ambiguity in the comment.
137
+
138
+
### Important words buried at the end
139
+
140
+
- Front-load the important information.
141
+
- Preferred: "Connection successful. Configure your data source settings."
142
+
- Avoid: "The connection was successful and you can now proceed to configure the data source settings."
143
+
144
+
### Missing context
145
+
146
+
- Strings should make sense outside of product context
147
+
- Don't depend on screen layout, position, or variables to complete a thought
148
+
- Give enough information for users (and translators) to understand the message
149
+
150
+
### Unnecessary words
151
+
152
+
- Do not include meta-labels in a string. For example, use "Delete" rather than "Delete Title" for a dialog title, and explain the context in the comment.
30
153
31
154
## How to Find Strings to Review
32
155
@@ -38,18 +161,17 @@ Apply these principles to all reviewed strings:
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments