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.

Sign up for GitHub

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

Jump to bottom

[localize] Fix and document msgdesc comments #1445

Merged
merged 3 commits into from Dec 4, 2020
Merged

[localize] Fix and document msgdesc comments #1445

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7844a49
Fix and document // msgdesc comments
aomarks Nov 24, 2020
2bbd805
Fix incorrect transform vs runtime table
aomarks Nov 24, 2020
e5ae771
Remove DOM typings, fix README nit
aomarks Dec 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 5 additions & 0 deletions packages/localize/CHANGELOG.md
View file
Open in desktop
Expand Up @@ -26,6 +26,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- It is no longer necessary to provide a message `id`. When omitted, an id will
be automatically generated from the string contents of the template.

### Fixed

- `// msgdesc` descriptions are now correctly emitted as XLIFF `<note>`
elements, instead of crashing.

## [0.5.1] - 2020-11-09

### Fixed
Expand Down
47 changes: 45 additions & 2 deletions packages/localize/README.md
View file
Open in desktop
Expand Up @@ -12,7 +12,7 @@

<img src="./rgb_lit.png" width="150" height="100" align="right"></img>

###### [Features](#features) | [Overview](#overview) | [Modes](#modes) | [Tutorial](#tutorial) | [API](#api) | [Status event](#lit-localize-status-event) | [Localized mixin](#localized-mixin) | [CLI](#cli) | [Config file](#config-file) | [FAQ](#faq)
###### [Features](#features) | [Overview](#overview) | [Modes](#modes) | [Tutorial](#tutorial) | [API](#api) | [Descriptions](#descriptions) | [Status event](#lit-localize-status-event) | [Localized mixin](#localized-mixin) | [CLI](#cli) | [Config file](#config-file) | [FAQ](#faq)

> @lit/localize is a library and command-line tool for localizing web
> applications that are based on lit-html and LitElement.
Expand Down Expand Up @@ -86,7 +86,7 @@ lit-localize supports two output modes: _transform_ and _runtime_.
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Output | A full build of your application for each locale, with all `msg` calls replaced with static localized templates. | A dynamically loadable template module for each target locale. |
| Make template localizable | `msg()` | `msg()` |
| Configure | `const {getLocale, setLocale} =`<br>`configureLocalization(...);` | (Optional)<br><br> `const {getLocale} =`<br>`configureTransformLocalization(...);` |
| Configure | (Optional)<br><br> `const {getLocale} =`<br>`configureTransformLocalization(...);` | `const {getLocale, setLocale} =`<br>`configureLocalization(...);` |
| Switch locales | Refresh page and load a different `.js` file | Call `setLocale()` and re-render using any of:<br><br>- `lit-localize-status` event<br>- `setLocale` promise<br>- `Localized` mixin for `LitElement` |
| Advantages | - Fastest rendering<br>- Fewer bytes for a single locale | - Faster locale switching<br>- Fewer _marginal_ bytes when switching locales |

Expand Down Expand Up @@ -376,6 +376,49 @@ html`Hola <b>${getUsername()}!</b>`;

Name of the [`lit-localize-status`](#lit-localize-status-event) event.

## Descriptions

You can add descriptions to messages using special `// msgdesc:` comments.
Message descriptions help translators understand the context of each string they
are translating.

```ts
// msgdesc: Greeting to everybody on homepage
msg(html`Hello <b>World</b>!`);
```

Descriptions are represented in XLIFF using `<note>` elements.

```xml
<trans-unit id="0h3c44aff2d5f5ef6b">
<note>Greeting to everybody on homepage</note>
<source>Hello <ph id="0">&lt;b></ph>World<ph id="1">&lt;/b></ph>!</source>
</trans-unit
```

You can also apply a `// msgdesc:` comment to a class, function, or block, in
which case the description will apply recursively to all `msg` calls within it.
If there are multiple descriptions that apply to a `msg` call, then they are
concatenated with a forward-slash in top-down order. This can be useful for
describing the context of an entire group of messages.

```ts
// msgdesc: Homepage
class MyHomepage extends Localized(LitElement) {
render() {
// msgdesc: Greeting to everybody
return msg(html`Hello <b>World</b>!`);
}
}
```

```xml
<trans-unit id="0h3c44aff2d5f5ef6b">
<note>Homepage / Greeting to everybody</note>
<source>Hello <ph id="0">&lt;b></ph>World<ph id="1">&lt;/b></ph>!</source>
</trans-unit>
```

## `lit-localize-status` event

In runtime mode, whenever a locale change starts, finishes successfully, or
Expand Down
3 changes: 2 additions & 1 deletion packages/localize/src/formatters/xliff.ts
View file
Open in desktop
Expand Up @@ -250,9 +250,10 @@ export class XliffFormatter implements Formatter {

if (descStack.length > 0) {
// https://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html#note
const note = document.createElement('note');
const note = doc.createElement('note');
Copy link
Collaborator

Choose a reason for hiding this comment

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

ouch!

Can you remove the "DOM" lib from the tsconfig? Hopefully TS would catch this.

Copy link
Member Author

@aomarks aomarks Dec 4, 2020 •
edited

Choose a reason for hiding this comment

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

Done. (But DOM types still get loaded because the xmldom package I'm loading has a reference to them)

Copy link
Collaborator

Choose a reason for hiding this comment

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

Filed an issue here: DefinitelyTyped/DefinitelyTyped#49953

note.appendChild(doc.createTextNode(descStack.join(' / ')));
transUnit.appendChild(note);
indent(transUnit, 1);
}

// https://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html#source
Expand Down
11 changes: 11 additions & 0 deletions packages/localize/testdata/xliff/goldens/foo.ts
View file
Open in desktop
Expand Up @@ -31,3 +31,14 @@ msg(`Hello World!`);
msg((name) => `Hello ${name}!`, {args: ['Friend']});
msg(html`Hello <b>World</b>!`);
msg((name) => html`Hello <b>${name}</b>!`, {args: ['Friend']});

// msgdesc: Description of 0
msg('described 0');

// msgdesc: Parent description
export function described() {
// msgdesc: Description of 1
msg('described 1');
// msgdesc: Description of 2
msg('described 2');
}
3 changes: 3 additions & 0 deletions packages/localize/testdata/xliff/goldens/tsout/es-419.ts
View file
Open in desktop
Expand Up @@ -23,4 +23,7 @@ export const templates = {
<b>${x}</b>
<i>y</i>
<b>${x}</b>`,
as03c68d79ad36e8d4: `described 0`,
as03c68e79ad36ea87: `described 1`,
as03c68f79ad36ec3a: `described 2`,
};
3 changes: 3 additions & 0 deletions packages/localize/testdata/xliff/goldens/tsout/zh_CN.ts
View file
Open in desktop
Expand Up @@ -23,4 +23,7 @@ export const templates = {
as00ad08ebae1e0f74: (name: any) => `Hello ${name}!`,
ah3c44aff2d5f5ef6b: html`Hello <b>World</b>!`,
ah82ccc38d4d46eaa9: (name: any) => html`Hello <b>${name}</b>!`,
as03c68d79ad36e8d4: `described 0`,
as03c68e79ad36ea87: `described 1`,
as03c68f79ad36ec3a: `described 2`,
};
12 changes: 12 additions & 0 deletions packages/localize/testdata/xliff/goldens/xliff/es-419.xlf
View file
Open in desktop
Expand Up @@ -48,6 +48,18 @@
<source>Hello <ph id="0">&lt;b>${name}&lt;/b></ph>!</source>
<target>Hola <ph id="0">&lt;b>${name}&lt;/b></ph>!</target>
</trans-unit>
<trans-unit id="as03c68d79ad36e8d4">
<note>Description of 0</note>
<source>described 0</source>
</trans-unit>
<trans-unit id="as03c68e79ad36ea87">
<note>Parent description / Description of 1</note>
<source>described 1</source>
</trans-unit>
<trans-unit id="as03c68f79ad36ec3a">
<note>Parent description / Description of 2</note>
<source>described 2</source>
</trans-unit>
</body>
</file>
</xliff>
12 changes: 12 additions & 0 deletions packages/localize/testdata/xliff/goldens/xliff/zh_CN.xlf
View file
Open in desktop
Expand Up @@ -39,6 +39,18 @@
<trans-unit id="ah82ccc38d4d46eaa9">
<source>Hello <ph id="0">&lt;b>${name}&lt;/b></ph>!</source>
</trans-unit>
<trans-unit id="as03c68d79ad36e8d4">
<note>Description of 0</note>
<source>described 0</source>
</trans-unit>
<trans-unit id="as03c68e79ad36ea87">
<note>Parent description / Description of 1</note>
<source>described 1</source>
</trans-unit>
<trans-unit id="as03c68f79ad36ec3a">
<note>Parent description / Description of 2</note>
<source>described 2</source>
</trans-unit>
</body>
</file>
</xliff>
11 changes: 11 additions & 0 deletions packages/localize/testdata/xliff/input/foo.ts
View file
Open in desktop
Expand Up @@ -31,3 +31,14 @@ msg(`Hello World!`);
msg((name) => `Hello ${name}!`, {args: ['Friend']});
msg(html`Hello <b>World</b>!`);
msg((name) => html`Hello <b>${name}</b>!`, {args: ['Friend']});

// msgdesc: Description of 0
msg('described 0');

// msgdesc: Parent description
export function described() {
// msgdesc: Description of 1
msg('described 1');
// msgdesc: Description of 2
msg('described 2');
}