Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add best practices to i18n docs #2693

Closed
wants to merge 2 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 89 additions & 2 deletions packages/editor-ui/src/plugins/i18n/docs/ADDENDUM.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,12 +103,99 @@ Currently only the keys `oauth.clientId` and `oauth.clientSecret` are supported

### Special cases

`eventTriggerDescription` is a dynamic node property that is not part of node parameters. To translate it, set the `eventTriggerDescription` key at the root level of the `nodeView` property in the node translation file.
`eventTriggerDescription` and `activationMessage` are dynamic node properties that are not part of node parameters. To translate them, set the key at the root level of the `nodeView` property in the node translation file.

Webhook node:

```json
{
"nodeView": {
"eventTriggerDescription": "🇩🇪 Waiting for you to call the Test URL"
"eventTriggerDescription": "🇩🇪 Waiting for you to call the Test URL",
}
}
```

Cron node:

```json
{
"nodeView": {
"activationMessage": "🇩🇪 'Your cron trigger will now trigger executions on the schedule you have defined."
}
}
```

## Best practices for UI development

When creating a new component, create a new component key in `en.json` with the component name in camel case. Place the key in `en.json` in alphabetical order.

In most cases, the new component is created in `/components`, e.g. `/components/About.vue`. But if the component is created in a nested dir, e.g. `/components/CredentialEdit/CredentialConfig.vue`, ensure this nesting is reflected in `en.json`.

```json
{
"credentialEdit": {
"credentialConfig": {
"accountConnected": "Account connected"
}
Comment on lines +132 to +139
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this really a good idea? would not this mean we have to rename keys every time we refactor. would prefer to keep keys as flat as possible

Copy link
Contributor Author

@ivov ivov Jan 18, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition to the dir case, there are potentially more levels of nesting: dir > component > symbol > toast. Rephrasing a display string, renaming a component or dir, refactoring a component, they all require updating the translation file.

I don't disagree that this coupling is not ideal, but if we flatten the object, the translations file becomes less organized, and we lose the ability to translate the same keys in different ways when in different contexts. Enforcing nesting to avoid key clashes was the motivation for reworking how nested node params are translated in the latest i18n refactorings.

}
}
```

The translation key should be the display string in camel case, cropped if too long. HTML is allowed in the display string.

```json
{
"workflowActivator": {
"theWorkflowIsSetToBeActiveBut": "The workflow is set to be active but could not be started.<br />Click to display error message."
}
}
```

As an exception, keys for toast contents should use `message` and `title`.

```json
{
"workflowRun": {
"noActiveConnectionToTheServer": "No active connection to server. It is maybe down.",
"showMessage": {
"message": "The workflow has issues. Please fix them first",
"title": "Workflow cannot be executed"
}
}
}
```

Differentiate multiple toasts with symbols from the code (e.g. method name) and if needed with numbers.

```json
{
"workflowSettings": {
"showError": {
"saveSettings1": {
"errorMessage": "Timeout is activated but set to 0",
"message": "There was a problem saving the settings",
"title": "Problem saving settings"
},
"saveSettings2": {
"errorMessage": "Maximum Timeout is: {hours} hours, {minutes} minutes, {seconds} seconds",
"message": "Set timeout is exceeding the maximum timeout!",
"title": "Problem saving settings"
},
"saveSettings3": {
"message": "There was a problem saving the settings",
"title": "Problem saving settings"
}
}
}
}
```

Escape double quotes.

```json
{
"tagsDropdown": {
"createTag": "Create tag \"{filter}\"",
}
}
```