-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathangular_translate.angular.txt
200 lines (178 loc) · 13.7 KB
/
angular_translate.angular.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ANGULAR_TRANSLATE ┃
┗━━━━━━━━━━━━━━━━━━━━━━━┛
VERSION ==> #2.6.1
#Do i18n client-side, with lazy loading.
#Components:
# - MODULE "pascalprecht.translate"
# - PROVIDER $translateProvider
# - SERVICE $translate
# - FILTER translate()
┌──────────────┐
│ LANGUAGE │
└──────────────┘
TRANSLATE.use() #Returns LANG_STR
TRANSLATE.use(LANG_STR) #Changes language. Returns PROMISE.
TRANSLATEPROVIDER. #Sets default language according to browser settings:
determinePreferredLanguage() # - check navigator.languages[0]|language|browser|system|userLanguage LANG_VAL
# - can teach association between LANG_VAL and LANG_STR with:
# TRANSLATEPROVIDER.registerAvailableLanguageKeys(LANG_STR_ARR, {LANG_VAL:LANG_STR ...})
# where LANG_STR_ARR is just the concatenation of all LANG_STR of the next object
# - only need to teach when LANG_VAL !== LANG_STR
TRANSLATEPROVIDER.
determinePreferredLanguage
(FUNC()->LANG_STR)
TRANSLATEPROVIDER.
preferredLanguage(LANG_STR) #Sets default language explicitely
TRANSLATE.preferredLanguage() #Returns it
TRANSLATE[PROVIDER]. #When cannot find TRANS_KEY in current LANG2_STR, use LANG_STR.
fallbackLanguage(LANG_STR[_ARR]) #Use TRANSLATEPROVIDER config-time, TRANSLATE run-time.
#Difference between default language and fallback language:
# - default language is what the first TRANSLATE.use(LANG_STR) implicitely called
# - fallback language is when translation cannot be found
TRANSLATE.fallbackLanguage() #Returns it
TRANSLATE.useFallbackLanguage #When fallbackLanguage are LANG_STR_ARR, make current list start at the index where LANG_STR
(LANG_STR) #is in the array. Rare use cases.
TRANSLATEPROVIDER.useStorage #Remembers current LANG_STR using SERVICE, which must be OBJ:
(SERVICE_STR) # - get(KEY_STR)->LANG_STR
# - put(KEY_STR, LANG_STR)
TRANSLATE.storage() #Returns SERVICE
TRANSLATEPROVIDER.storageKey(STR) #Sets KEY_STR
TRANSLATE.storageKey() #Returns KEY_STR (def: "NG_TRANSLATE_LANG_KEY")
TRANSLATPROVIDR.storagePrefix(STR)#Prepended to storageKey
TRANSLATEPROVIDER. #Remembers current LANG_STR in cookie or localStorage.
useCookie|LanguageStorage() #Must use extra package angular-translate-storage-cookie|local
#Can use SERVICE $translateCookie|LanguageStorage, with methods get|put() (see below)
#LanguageStorage has fallback on CookieStorage, so depends on it.
#CookieStorage depends on ngCookies, which:
# - only stores after $digest.
# - sets document.cookie, which does not work when on Chrome and using file:///
┌──────────────────┐
│ TRANSLATIONS │
└──────────────────┘
FLICKERING ==> #TRANSLATEPROVIDER.translations() is sync, TRANSLATEPROVIDER.use*Loader() async.
#async has priority but sync should be used too in order to provider default language while
#async is loading and avoid flickering.
#So should use TRANSLATEPROVIDER.translations() + TRANSLATEPROVIDER.use*Loader()
<any> #Adds temporarily CSS class STR (def: "translate-cloak") while loader is running (stops at
translate-cloak["=TRANS_KEY"] #$translateChangeEnd).
#Goal is to put as invisible while loader is running, to avoid flickering.
#TRANS_KEY can be specified if there are partial loaders involved (so not one global loader).
TRANSLATEPROVIDER.cloakClassName
(STR) #Sets def. cloak class name
TRANSLATE.cloakClassName() #Gets def. cloak class name
TRANSLATEPROVIDER. #If STR is "escaped" (def: null), HTML escape interpolated values (from TRANS_OBJ)
useSanitizeValueStrategy(STR) #in TRANSL_STR.
#Helps avoiding XSS if TRANS_LIST is not trusted.
TRANS_LIST #Is OBJ, with { TRANS_KEY TRANSL_STR ... }:
# - TRANSL_STR is the translated text
# - TRANS_KEY can be nested, e.g. OBJ.VAR.VAR2 uses TRANS_KEY "VAR.VAR2"
# - when subkey is same as previous one, can omit it, e.g. "VAR.VAR2.VAR2" can be
# shortcut to "VAR.VAR2"
# - TRANSL_STR can be reference "@:TRANS_KEY"
INTERPOLATION ==> #Goal:
# - Allow TRANSL_STR to contain pattern that are substitued against a TRANS_OBJ
# - Has a type TRANS_INT and a SERVICE_STR
# - SERVICE must return OBJ:
# - interpolate(TRANSL_STR, TRANS_OBJ)->STR
# - getInterpolationIdentifier->TRANS_INT
# - setLocale(LANG_STR): informs SERVICE of the new language
# - Can only use one at a time for a given translation:
# - can specify TRANS_INT within TRANSLATE SERVICE, DIRECTIVE or FILTER
# - must first load with TRANSLATEPROVIDER.addInterpolation(SERVICE_STR)
# (already done for TRANS_INT "default")
# - Change default TRANS_INT with TRANSLATEPROVIDER.useInterpolation(SERVICE_STR)
# (TRANSLATEPROVIDER.useMessageFormatInterpolation() available too)
# - Available:
# - TRANS_INT "default" (def), SERVICE "$translateDefaultInterpolation"
# - transform {{VAR}} to TRANS_OBJ.VAR
# - TRANS_INT "messageformat", SERVICE "$translateMessageFormatInterpolation"
# - transform:
# - {STR_VAR, select, male|female|other{VAL}} according to TRANS_OBJ.VAR (gender)
# - {NUM_VAR, plural, zero|one|two|few|many|other{VAL}} according to TRANS_OBJ.VAR
# (plural)
# - male|female|... and zero|... are space-separated. "other" is always required.
# space after comma is optional.
# - must install packages messageformat and
# angular-translate-interpolation-messageformat
TRANSLATEPROVIDER.translations
(LANG_STR, TRANS_LIST) #Defines translation strings inline.
TRANSLATEPROVIDER.useLoader #Defines translation strings, but requests it only when needed, using SERVICE.
(SERVICE_STR, OBJ) #SERVICE must return FUNC(OBJ)->PROMISE, where PROMISE resolves to TRANS_LIST.
$translateStaticFilesLoader(OBJ) #useLoader() SERVICE, which fetches from a file.
#Can also use TRANSLATEPROVIDER.useStaticFilesLoader(OBJ)
#Will fetch file {OBJ.prefix}{LANG_STR}{OBJ.suffix}
#Can also use OBJ_ARR: files OBJ if several locations
#Can also use OBJ.$http OBJ2, passed to $http(OBJ2)
#Must use extra package angular-translate-loader-static-files
$translateUrlLoader(URL|OBJ) #useLoader() SERVICE, which fetches from a URL.
#Can also use TRANSLATEPROVIDER.useUrlLoader(URL|OBJ)
#Will call URL?lang=LANG_STR, which should return TRANS_LIST
#OBJ a be:
# - url URL
# - $http OBJ2
# - query STR (def: "lang")
#Must use extra package angular-translate-loader-url
$translatePartialLoader #useLoader() SERVICE, which fetches from a URL, with possible URL patterns.
#Will call OBJ.urlTemplate STR, where STR can use patterns:
# - {part} PART_STR:
# - must:
# - call TRANSLATEPARTIALLOADER[PROVIDER].addPart(PART_STR)
# - which fires a $translatePartialLoaderStructureChanged event on $rootScope
# - if using the SERVICE (not PROVIDER), call TRANSLATE.refresh()->PROMISE
# Can do it in $translatePartialLoaderStructureChanged event handler
# - this allow lazy loading not only according to language, but also of part of the
# application user is in
# - can also:
# - TRANSLATE[PROVIDER].deletePart(PART_STR)
# - TRANSLATEPROVIDER.getRegisteredParts()->PART_STR_ARR
# - TRANSLATE[PROVIDER].isPartAvailable(PART_STR): added, but not necessary loaded
# - TRANSLATEPROVIDER.isPartLoaded(PART_STR, LANG_STR)
# - {lang} LANG_STR
#Must use extra package angular-translate-loader-partial
TRANSLATEPROVIDER.useLoaderCache #If not false (def), use $http caching with TRANSLATEPROVIDER.*Loader()
(BOOL|CACHE|SERVICE_STR) #SERVICE must return a CACHE.
TRANSLATE.loaderCache() #Returns it
TRANSLATE.refresh(LANG_STR) #Call the loader again.
┌─────────────────┐
│ TRANSLATING │
└─────────────────┘
TRANSLATE[.instant] #Returns PROMISE resolving to TRANSL_STR or (if ARR) OBJ.TRANS_KEY TRANSL_STR
(TRANS_KEY[_ARR][, TRANS_OBJ] #If "instant", returns sync (no PROMISE)
[, TRANS_INT]) #Should be wrapped by $rootScope.on("$translateChangeSuccess", FUNC())
translate(TRANS_KEY[, TRANS_OBJ]
[, TRANS_INT]) #FILTER
<any>
translate[="TRANS_KEY"] #Replace children by TRANSL_STR. TRANS_KEY by def. is children textContent
#Can define priority with TRANSLATEPROVIDER.directivePriority(NUM)
translate-values="TRANS_OBJ"
translate-value-VAR="VAL" #Same as translate-values="{ VAR: VAL }"
translate-interpolation=
"TRANS_INT"
translate-attr-ATTR="TRANS_KEY" #Adds HTML attribute ATTR="TRANSL_STR"
TRANSLATEPROVIDER. #Called when no translation found. SERVICE must return FUNC(TRANS_KEY, LANG_STR)->TRANSL_STR
useMissingTranslationHandler #If does not return anything, tries next handler.
(SERVICE_STR) #By def., by order of priority:
# - use <any translate-default="VAL"> if this DIRECTIVE is used
# - tries each handler
# - returns TRANS_KEY
$translateMissingTranslation #SERVICE that can be used with useMissingTranslationHandler() which does $log.warn()
HandlerLog #Must install package angular-translate-handler-log
#Can also use TRANSLATEPROVIDER.useMissingTranslationHandlerLog()
┌───────────┐
│ OTHER │
└───────────┘
TRANSLATEPROVIDER.usePostCompiling
(BOOL)
<any>
translate-compile["=BOOL_EXPR"] #Fires $compile(AJQ)(SCOPE) after translating.
TRANSLATEPROVIDER.
isPostCompilingEnabled() #
$rootScope.on
("$translateChangeStart",FUNC()) #Fired when loading TRANS_OBJ or changing LANG_STR
$rootScope.on
("$translateChangeSuccess|Error|
End",FUNC()) #Fired when done loading TRANS_OBJ or changing LANG_STR (no error, error, or either)
$rootScope.on
("$translateLoading*", FUNC()) #Same as $translateChange* but only for use*Loading()
TESTING ==> #Should use sync loading instead of async for unit testing.