The Angular extractor generates a file with a translation unit entry each of the following instances.
- Each
i18n
attribute in a component template
- Each
$localize
tagged message string in component code
As described in
How meanings control text extraction and merges
, Angular assigns each translation unit a unique ID.
The following example displays translation units with unique IDs.
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<
xliff
version
=
"1.2"
xmlns
=
"urn:oasis:names:tc:xliff:document:1.2"
>
<
file
source-language
=
"en"
datatype
=
"plaintext"
original
=
"ng2.template"
>
<
body
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
target
>
Bonjour i18n !
</
target
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3"
datatype
=
"html"
>
<
source
>
I don't output any element
</
source
>
<
target
>
Je n'affiche aucun element
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"701174153757adf13e7c24a248c8a873ac9f5193"
datatype
=
"html"
>
<
source
>
Angular logo
</
source
>
<
target
>
Logo d'Angular
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"5a134dee893586d02bffc9611056b9cadf9abfad"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"f99f34ac9bd4606345071bd813858dec29f3b7d1"
datatype
=
"html"
>
<
source
>
The author is
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
source
>
<
target
>
L'auteur est
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"eff74b75ab7364b6fa888f1cbfae901aaaf02295"
datatype
=
"html"
>
<
source
>
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}
</
source
>
<
target
>
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c"
datatype
=
"html"
>
<
source
>
Updated:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
source
>
<
target
>
Mis a jour:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"7151c2e67748b726f0864fc443861d45df21d706"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago by
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes par
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"myId"
datatype
=
"html"
>
<
source
>
Hello
</
source
>
<
target
state
=
"new"
>
Bonjour
</
target
>
</
trans-unit
>
</
body
>
</
file
>
</
xliff
>
When you change the translatable text, the extractor generates a new ID for that translation unit.
In most cases, changes in the source text also require a change to the translation.
Therefore, using a new ID keeps the text change in sync with translations.
However, some translation systems require a specific form or syntax for the ID.
To address the requirement, use a custom ID to mark text.
Most developers don't need to use a custom ID.
If you want to use a unique syntax to convey additional metadata, use a custom ID.
Additional metadata may include the library, component, or area of the application in which the text appears.
To specify a custom ID in the
i18n
attribute or
$localize
tagged message string, use the
@@
prefix.
The following example defines the
introductionHeader
custom ID in a heading element.
<
h1
>
Hello i18n!
</
h1
>
<
h1
i18n
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"@@introductionHeader"
>
Hello i18n!
</
h1
>
<
img
[
src
]=
"logo"
title
=
"Angular logo"
alt
=
"Angular logo"
>
<
h3
i18n
=
"@@myId"
>
Hello
</
h3
>
<
p
i18n
=
"@@myId"
>
Good bye
</
p
>
The following example defines the
introductionHeader
custom ID for a variable.
variableText1 = $localize
`:@@introductionHeader:Hello i18n!`
;
When you specify a custom ID, the extractor generates a translation unit with the custom ID.
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<
xliff
version
=
"1.2"
xmlns
=
"urn:oasis:names:tc:xliff:document:1.2"
>
<
file
source-language
=
"en"
datatype
=
"plaintext"
original
=
"ng2.template"
>
<
body
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
target
>
Bonjour i18n !
</
target
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3"
datatype
=
"html"
>
<
source
>
I don't output any element
</
source
>
<
target
>
Je n'affiche aucun element
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"701174153757adf13e7c24a248c8a873ac9f5193"
datatype
=
"html"
>
<
source
>
Angular logo
</
source
>
<
target
>
Logo d'Angular
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"5a134dee893586d02bffc9611056b9cadf9abfad"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"f99f34ac9bd4606345071bd813858dec29f3b7d1"
datatype
=
"html"
>
<
source
>
The author is
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
source
>
<
target
>
L'auteur est
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"eff74b75ab7364b6fa888f1cbfae901aaaf02295"
datatype
=
"html"
>
<
source
>
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}
</
source
>
<
target
>
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c"
datatype
=
"html"
>
<
source
>
Updated:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
source
>
<
target
>
Mis a jour:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"7151c2e67748b726f0864fc443861d45df21d706"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago by
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes par
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"myId"
datatype
=
"html"
>
<
source
>
Hello
</
source
>
<
target
state
=
"new"
>
Bonjour
</
target
>
</
trans-unit
>
</
body
>
</
file
>
</
xliff
>
If you change the text, the extractor does not change the ID.
As a result, you don't have to take the extra step to update the translation.
The drawback of using custom IDs is that if you change the text, your translation may be out-of-sync with the newly changed source text.
Use a custom ID in combination with a description and a meaning to further help the translator.
The following example includes a description, followed by the custom ID.
<
h1
>
Hello i18n!
</
h1
>
<
h1
i18n
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"@@introductionHeader"
>
Hello i18n!
</
h1
>
<
img
[
src
]=
"logo"
title
=
"Angular logo"
alt
=
"Angular logo"
>
<
h3
i18n
=
"@@myId"
>
Hello
</
h3
>
<
p
i18n
=
"@@myId"
>
Good bye
</
p
>
The following example defines the
introductionHeader
custom ID and description for a variable.
variableText2 = $localize
`:An introduction header for this sample@@introductionHeader:Hello i18n!`
;
The following example adds a meaning.
<
h1
>
Hello i18n!
</
h1
>
<
h1
i18n
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"@@introductionHeader"
>
Hello i18n!
</
h1
>
<
img
[
src
]=
"logo"
title
=
"Angular logo"
alt
=
"Angular logo"
>
<
h3
i18n
=
"@@myId"
>
Hello
</
h3
>
<
p
i18n
=
"@@myId"
>
Good bye
</
p
>
The following example defines the
introductionHeader
custom ID for a variable.
variableText3 = $localize
`:site header|An introduction header for this sample@@introductionHeader:Hello i18n!`
;
Be sure to define custom IDs that are unique.
If you use the same ID for two different text elements, the extraction tool extracts only the first one, and Angular uses the translation in place of both original text elements.
For example, in the following code snippet the same
myId
custom ID is defined for two different text elements.
<
h1
>
Hello i18n!
</
h1
>
<
h1
i18n
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"site header|An introduction header for this sample@@introductionHeader"
>
Hello i18n!
</
h1
>
<
h1
i18n
=
"@@introductionHeader"
>
Hello i18n!
</
h1
>
<
img
[
src
]=
"logo"
title
=
"Angular logo"
alt
=
"Angular logo"
>
<
h3
i18n
=
"@@myId"
>
Hello
</
h3
>
<
p
i18n
=
"@@myId"
>
Good bye
</
p
>
The following displays the translation in French.
<?xml version=
"1.0"
encoding=
"UTF-8"
?>
<
xliff
version
=
"1.2"
xmlns
=
"urn:oasis:names:tc:xliff:document:1.2"
>
<
file
source-language
=
"en"
datatype
=
"plaintext"
original
=
"ng2.template"
>
<
body
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"introductionHeader"
datatype
=
"html"
>
<
source
>
Hello i18n!
</
source
>
<
target
>
Bonjour i18n !
</
target
>
<
note
priority
=
"1"
from
=
"description"
>
An introduction header for this sample
</
note
>
<
note
priority
=
"1"
from
=
"meaning"
>
User welcome
</
note
>
</
trans-unit
>
<
trans-unit
id
=
"ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3"
datatype
=
"html"
>
<
source
>
I don't output any element
</
source
>
<
target
>
Je n'affiche aucun element
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"701174153757adf13e7c24a248c8a873ac9f5193"
datatype
=
"html"
>
<
source
>
Angular logo
</
source
>
<
target
>
Logo d'Angular
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"5a134dee893586d02bffc9611056b9cadf9abfad"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"f99f34ac9bd4606345071bd813858dec29f3b7d1"
datatype
=
"html"
>
<
source
>
The author is
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
source
>
<
target
>
L'auteur est
<
x
id
=
"ICU"
equiv-text
=
"
{gender,
select
, male {...}
female
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"eff74b75ab7364b6fa888f1cbfae901aaaf02295"
datatype
=
"html"
>
<
source
>
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}
</
source
>
<
target
>
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c"
datatype
=
"html"
>
<
source
>
Updated:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
source
>
<
target
>
Mis a jour:
<
x
id
=
"ICU"
equiv-text
=
"
{minutes, plural, =0 {...}
=1
{...}
other
{...}
}"
/>
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"7151c2e67748b726f0864fc443861d45df21d706"
datatype
=
"html"
>
<
source
>
{VAR_PLURAL, plural, =0 {just now}
=1
{one minute ago}
other
{<x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes ago by
{VAR_SELECT,
select
, male {male}
female
{female}
other
{other}
}} }
</
source
>
<
target
>
{VAR_PLURAL, plural, =0 {a l'instant}
=1
{il y a une minute}
other
{il y a <x id="INTERPOLATION" equiv-text="{{minutes}
}"/> minutes par
{VAR_SELECT,
select
, male {un homme}
female
{une femme}
other
{autre}
}} }
</
target
>
</
trans-unit
>
<
trans-unit
id
=
"myId"
datatype
=
"html"
>
<
source
>
Hello
</
source
>
<
target
state
=
"new"
>
Bonjour
</
target
>
</
trans-unit
>
</
body
>
</
file
>
</
xliff
>
Both elements now use the same translation (
Bonjour
), because both were defined with the same custom ID.
<
h3
>
Bonjour
</
h3
>
<
p
>
Bonjour
</
p
>