001 /** 002 * Copyright (c) 2000-present Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.portal.kernel.util; 016 017 import com.liferay.portal.kernel.json.JSONObject; 018 import com.liferay.portal.kernel.settings.LocalizedValuesMap; 019 import com.liferay.portal.kernel.settings.Settings; 020 import com.liferay.portal.kernel.xml.Document; 021 022 import java.util.Collection; 023 import java.util.Locale; 024 import java.util.Map; 025 026 import javax.portlet.PortletPreferences; 027 import javax.portlet.PortletRequest; 028 029 import javax.servlet.http.HttpServletRequest; 030 031 /** 032 * Stores and retrieves localized strings from XML, and provides utility methods 033 * for updating localizations from JSON, portlet requests, and maps. Used for 034 * adding localization to strings, most often for model properties. 035 * 036 * <p> 037 * Localized values are cached in this class rather than in the value object 038 * since value objects get flushed from cache fairly quickly. Though lookups 039 * performed on a key based on an XML file are slower than lookups done at the 040 * value object level in general, the value object will get flushed at a rate 041 * which works against the performance gain. The cache is a soft hash map which 042 * prevents memory leaks within the system while enabling the cache to live 043 * longer than in a weak hash map. 044 * </p> 045 * 046 * @author Alexander Chow 047 * @author Jorge Ferrer 048 * @author Mauro Mariuzzo 049 * @author Julio Camarero 050 * @author Brian Wing Shun Chan 051 */ 052 public interface Localization { 053 054 /** 055 * Deserializes the JSON object into a map of locales and localized strings. 056 * 057 * @param jsonObject the JSON object 058 * @return the locales and localized strings 059 */ 060 public Object deserialize(JSONObject jsonObject); 061 062 public String[] getAvailableLanguageIds(Document document); 063 064 /** 065 * Returns the available locales from the localizations XML. 066 * 067 * @param xml the localizations XML 068 * @return the language IDs of the available locales 069 */ 070 public String[] getAvailableLanguageIds(String xml); 071 072 /** 073 * Returns a valid default locale for importing a localized entity. 074 * 075 * @param className the class name of the entity 076 * @param classPK the primary keys of the entity 077 * @param contentDefaultLocale the default Locale of the entity 078 * @param contentAvailableLocales the available locales of the entity 079 * @return the valid locale 080 */ 081 public Locale getDefaultImportLocale( 082 String className, long classPK, Locale contentDefaultLocale, 083 Locale[] contentAvailableLocales); 084 085 public String getDefaultLanguageId(Document document); 086 087 public String getDefaultLanguageId(Document document, Locale defaultLocale); 088 089 /** 090 * Returns the default locale from the localizations XML. 091 * 092 * @param xml the localizations XML 093 * @return the language ID of the default locale, or the system default 094 * locale if the default locale cannot be retrieved from the XML 095 */ 096 public String getDefaultLanguageId(String xml); 097 098 public String getDefaultLanguageId(String xml, Locale defaultLocale); 099 100 /** 101 * Returns the localized string from the localizations XML in the language. 102 * The default language is used if no localization exists for the requested 103 * language. 104 * 105 * @param xml the localizations XML 106 * @param requestedLanguageId the ID of the language 107 * @return the localized string 108 */ 109 public String getLocalization(String xml, String requestedLanguageId); 110 111 /** 112 * Returns the localized string from the localizations XML in the language, 113 * optionally using the default language if no localization exists for the 114 * requested language. 115 * 116 * @param xml the localizations XML 117 * @param requestedLanguageId the ID of the language 118 * @param useDefault whether to use the default language if no localization 119 * exists for the requested language 120 * @return the localized string, or an empty string if 121 * <code>useDefault</code> is <code>false</code> and no localization 122 * exists for the requested language 123 */ 124 public String getLocalization( 125 String xml, String requestedLanguageId, boolean useDefault); 126 127 /** 128 * Returns the localized string from the localizations XML in the language, 129 * optionally using the default language if no localization exists for the 130 * requested language. If no localization exists, the default value is 131 * returned. 132 * 133 * @param xml the localizations XML 134 * @param requestedLanguageId the ID of the language 135 * @param useDefault whether to use the default language if no localization 136 * exists for the requested language 137 * @param defaultValue the value returned if no localization exists 138 * @return the localized string, or the <code>defaultValue</code> if 139 * <code>useDefault</code> is <code>false</code> and no localization 140 * exists for the requested language 141 */ 142 public String getLocalization( 143 String xml, String requestedLanguageId, boolean useDefault, 144 String defaultValue); 145 146 /** 147 * Returns a map of locales and localized strings for the key. If no 148 * localization exists for a locale or the localization matches the default 149 * locale, that locale is not included in the map. 150 * 151 * @param locales the locales to be used in the map 152 * @param defaultLocale the default locale 153 * @param key the language key to be translated 154 * @return the locales and localized strings for the key 155 */ 156 public Map<Locale, String> getLocalizationMap( 157 Collection<Locale> locales, Locale defaultLocale, String key); 158 159 /** 160 * Returns a map of locales and localized strings for the parameter in the 161 * request. 162 * 163 * @param request the request 164 * @param parameter the prefix of the parameters containing the localized 165 * strings. Each localization is loaded from a parameter with this 166 * prefix, followed by an underscore, and the language ID. 167 * @return the locales and localized strings 168 */ 169 public Map<Locale, String> getLocalizationMap( 170 HttpServletRequest request, String parameter); 171 172 /** 173 * Returns a map of locales and localized strings for the preference in the 174 * preferences container. 175 * 176 * @param preferences the preferences container 177 * @param preferenceName the prefix of the preference containing the 178 * localized strings. Each localization is loaded from a preference 179 * with this prefix, followed by an underscore, and the language ID. 180 * @return the locales and localized strings 181 */ 182 public Map<Locale, String> getLocalizationMap( 183 PortletPreferences preferences, String preferenceName); 184 185 /** 186 * Returns a map of locales and localized strings for the preference in the 187 * preferences container. If no localization exists for the preference in 188 * the default locale, the value of the property is used as the localization 189 * for it. 190 * 191 * @param preferences the preferences container 192 * @param preferenceName the prefix of the preference containing the 193 * localized strings. Each localization is loaded from a preference 194 * with this prefix, followed by an underscore, and the language ID. 195 * @param propertyName the name of the property whose value is used as the 196 * localization for the default locale, if no localization exists 197 * for it 198 * @return the locales and localized strings 199 */ 200 public Map<Locale, String> getLocalizationMap( 201 PortletPreferences preferences, String preferenceName, 202 String propertyName); 203 204 public Map<Locale, String> getLocalizationMap( 205 PortletPreferences preferences, String preferenceName, 206 String propertyName, String defaultPropertyValue, 207 ClassLoader classLoader); 208 209 /** 210 * Returns a map of locales and localized strings for the parameter in the 211 * portlet request. 212 * 213 * @param portletRequest the portlet request 214 * @param parameter the prefix of the parameters containing the localized 215 * strings. Each localization is loaded from a parameter with this 216 * prefix, followed by an underscore, and the language ID. 217 * @return the locales and localized strings 218 */ 219 public Map<Locale, String> getLocalizationMap( 220 PortletRequest portletRequest, String parameter); 221 222 public Map<Locale, String> getLocalizationMap( 223 PortletRequest portletRequest, String parameter, 224 Map<Locale, String> defaultValues); 225 226 /** 227 * Returns a map of locales and localized strings from the localizations 228 * XML. 229 * 230 * @param xml the localizations XML 231 * @return the locales and localized strings 232 */ 233 public Map<Locale, String> getLocalizationMap(String xml); 234 235 public Map<Locale, String> getLocalizationMap( 236 String xml, boolean useDefault); 237 238 public Map<Locale, String> getLocalizationMap( 239 String bundleName, ClassLoader classLoader, String key, 240 boolean includeBetaLocales); 241 242 /** 243 * Returns a map of locales and localized strings for the given languageIds 244 * and values. 245 * 246 * @param languageIds the languageIds of the localized Strings 247 * @param values the localized strings for the different languageId 248 * @return the map of locales and values for the given parameters 249 */ 250 public Map<Locale, String> getLocalizationMap( 251 String[] languageIds, String[] values); 252 253 /** 254 * Returns the localizations XML for the parameter from the portlet request, 255 * attempting to get data from the preferences container if it is not 256 * available in the portlet request. 257 * 258 * @param preferences the preferences container 259 * @param portletRequest the portlet request 260 * @param parameter the prefix of the parameters containing the localized 261 * strings. Each localization is loaded from a parameter with this 262 * prefix, followed by an underscore, and the language ID. 263 * @return the locales and localized strings 264 */ 265 public String getLocalizationXmlFromPreferences( 266 PortletPreferences preferences, PortletRequest portletRequest, 267 String parameter); 268 269 /** 270 * Returns the localizations XML for the parameter from the portlet request, 271 * attempting to get data from the preferences container if it is not 272 * available in the portlet request. If no localization exists in the 273 * default locale, the default value is used as the localization for it. 274 * 275 * @param preferences the preferences container 276 * @param portletRequest the portlet request 277 * @param parameter the prefix of the parameters containing the localized 278 * strings. Each localization is loaded from a parameter with this 279 * prefix, followed by an underscore, and the language ID. 280 * @param defaultValue the value used as the localization for the default 281 * locale, if no localization exists for it 282 * @return the locales and localized strings 283 */ 284 public String getLocalizationXmlFromPreferences( 285 PortletPreferences preferences, PortletRequest portletRequest, 286 String parameter, String defaultValue); 287 288 /** 289 * Returns the localizations XML for the prefixed parameter from the portlet 290 * request, attempting to get data from the preferences container if it is 291 * not available in the portlet request. If no localization exists for the 292 * the default locale, the default value is used as the localization for it. 293 * 294 * @param preferences the preferences container 295 * @param portletRequest the portlet request 296 * @param parameter the prefix of the parameters containing the localized 297 * strings. Each localization is loaded from a parameter with this 298 * prefix, followed by an underscore, and the language ID. 299 * @param prefix the value used in the request to prefix the parameter name 300 * @param defaultValue the value used as the localization for the default 301 * locale, if no localization exists for it 302 * @return the locales and localized strings, or the 303 * <code>defaultValue</code> if no localization exists 304 */ 305 public String getLocalizationXmlFromPreferences( 306 PortletPreferences preferences, PortletRequest portletRequest, 307 String parameter, String prefix, String defaultValue); 308 309 /** 310 * Returns the localized name in the language. The localized name is the 311 * name, followed by an underscore, and the language ID. 312 * 313 * @param name the name to be localized 314 * @param languageId the ID of the language 315 * @return the localized name for the language 316 */ 317 public String getLocalizedName(String name, String languageId); 318 319 public Map<Locale, String> getMap(LocalizedValuesMap localizedValuesMap); 320 321 /** 322 * Returns the localized preferences key in the language. Generally this is 323 * just the preferences key, followed by an underscore, and the language ID. 324 * 325 * @param key the preferences key 326 * @param languageId the ID of the language 327 * @return the localized preferences key 328 * @deprecated As of 7.0.0, replaced by {@link #getLocalizedName(String, 329 * String)} 330 */ 331 @Deprecated 332 public String getPreferencesKey(String key, String languageId); 333 334 /** 335 * Returns the localized preferences value for the key in the language. The 336 * default language is used if no localization exists for the requested 337 * language. 338 * 339 * @param preferences the preferences container 340 * @param key the preferences key 341 * @param languageId the ID of the language 342 * @return the localized preferences value 343 */ 344 public String getPreferencesValue( 345 PortletPreferences preferences, String key, String languageId); 346 347 /** 348 * Returns the localized preferences value for the key in the language, 349 * optionally using the default language if no localization exists for the 350 * requested language. 351 * 352 * @param preferences the preferences container 353 * @param key the preferences key 354 * @param languageId the ID of the language 355 * @param useDefault whether to use the default language if no localization 356 * exists for the requested language 357 * @return the localized preferences value, or an empty string if 358 * <code>useDefault</code> is <code>false</code> and no localization 359 * exists for the requested language 360 */ 361 public String getPreferencesValue( 362 PortletPreferences preferences, String key, String languageId, 363 boolean useDefault); 364 365 /** 366 * Returns the localized preferences values for the key in the language. The 367 * default language is used if no localization exists for the requested 368 * language. 369 * 370 * @param preferences the preferences container 371 * @param key the preferences key 372 * @param languageId the ID of the language 373 * @return the localized preferences values 374 */ 375 public String[] getPreferencesValues( 376 PortletPreferences preferences, String key, String languageId); 377 378 /** 379 * Returns the localized preferences values for the key in the language, 380 * optionally using the default language if no localization exists for the 381 * requested language. 382 * 383 * @param preferences the preferences container 384 * @param key the preferences key 385 * @param languageId the ID of the language 386 * @param useDefault whether to use the default language if no localization 387 * exists for the requested language 388 * @return the localized preferences values, or an empty string if 389 * <code>useDefault</code> is <code>false</code> and no localization 390 * exists for the requested language 391 */ 392 public String[] getPreferencesValues( 393 PortletPreferences preferences, String key, String languageId, 394 boolean useDefault); 395 396 /** 397 * Returns the localized settings value for the key in the language. The 398 * default language is used if no localization exists for the requested 399 * language. 400 * 401 * @param settings the settings 402 * @param key the settings key 403 * @param languageId the ID of the language 404 * @return the localized settings value 405 */ 406 public String getSettingsValue( 407 Settings settings, String key, String languageId); 408 409 /** 410 * Returns the localized settings value for the key in the language, 411 * optionally using the default language if no localization exists for the 412 * requested language. 413 * 414 * @param settings the settings 415 * @param key the settings key 416 * @param languageId the ID of the language 417 * @param useDefault whether to use the default language if no localization 418 * exists for the requested language 419 * @return the localized settings value. If <code>useDefault</code> is 420 * <code>false</code> and no localization exists for the requested 421 * language, an empty string is returned. 422 */ 423 public String getSettingsValue( 424 Settings settings, String key, String languageId, boolean useDefault); 425 426 /** 427 * Returns the localized settings values for the key in the language. The 428 * default language is used if no localization exists for the requested 429 * language. 430 * 431 * @param settings the settings 432 * @param key the settings key 433 * @param languageId the ID of the language 434 * @return the localized settings values 435 */ 436 public String[] getSettingsValues( 437 Settings settings, String key, String languageId); 438 439 /** 440 * Returns the localized settings values for the key in the language, 441 * optionally using the default language if no localization exists for the 442 * requested language. 443 * 444 * @param settings the settings 445 * @param key the settings key 446 * @param languageId the ID of the language 447 * @param useDefault whether to use the default language if no localization 448 * exists for the requested language 449 * @return the localized settings values. If <code>useDefault</code> is 450 * <code>false</code> and no localization exists for the requested 451 * language, an empty array is returned. 452 */ 453 public String[] getSettingsValues( 454 Settings settings, String key, String languageId, boolean useDefault); 455 456 public String getXml(LocalizedValuesMap localizedValuesMap, String key); 457 458 /** 459 * Removes the localization for the language from the localizations XML. The 460 * localized strings are stored as characters in the XML. 461 * 462 * @param xml the localizations XML 463 * @param key the name of the localized string, such as "Title" 464 * @param requestedLanguageId the ID of the language 465 * @return the localizations XML with the language removed 466 */ 467 public String removeLocalization( 468 String xml, String key, String requestedLanguageId); 469 470 /** 471 * Removes the localization for the language from the localizations XML, 472 * optionally storing the localized strings as CDATA in the XML. 473 * 474 * @param xml the localizations XML 475 * @param key the name of the localized string, such as "Title" 476 * @param requestedLanguageId the ID of the language 477 * @param cdata whether to store localized strings as CDATA in the XML 478 * @return the localizations XML with the language removed 479 */ 480 public String removeLocalization( 481 String xml, String key, String requestedLanguageId, boolean cdata); 482 483 /** 484 * Removes the localization for the language from the localizations XML, 485 * optionally storing the localized strings as CDATA in the XML. 486 * 487 * @param xml the localizations XML 488 * @param key the name of the localized string, such as "Title" 489 * @param requestedLanguageId the ID of the language 490 * @param cdata whether to store localized strings as CDATA in the XML 491 * @param localized whether there is a localized field 492 * @return the localizations XML with the language removed 493 */ 494 public String removeLocalization( 495 String xml, String key, String requestedLanguageId, boolean cdata, 496 boolean localized); 497 498 /** 499 * Sets the localized preferences values for the parameter in the portlet 500 * request. 501 * 502 * @param portletRequest the portlet request 503 * @param preferences the preferences container 504 * @param parameter the prefix of the parameters containing the localized 505 * strings. Each localization is loaded from a parameter with this 506 * prefix, followed by an underscore, and the language ID. 507 * @throws Exception if an exception occurred 508 */ 509 public void setLocalizedPreferencesValues( 510 PortletRequest portletRequest, PortletPreferences preferences, 511 String parameter) 512 throws Exception; 513 514 /** 515 * Sets the localized preferences value for the key in the language. 516 * 517 * @param preferences the preferences container 518 * @param key the preferences key 519 * @param languageId the ID of the language 520 * @param value the localized value 521 * @throws Exception if an exception occurred 522 */ 523 public void setPreferencesValue( 524 PortletPreferences preferences, String key, String languageId, 525 String value) 526 throws Exception; 527 528 /** 529 * Sets the localized preferences values for the key in the language. 530 * 531 * @param preferences the preferences container 532 * @param key the preferences key 533 * @param languageId the ID of the language 534 * @param values the localized values 535 * @throws Exception if an exception occurred 536 */ 537 public void setPreferencesValues( 538 PortletPreferences preferences, String key, String languageId, 539 String[] values) 540 throws Exception; 541 542 /** 543 * Updates the localized string for all the available languages in the 544 * localizations XML for the map of locales and localized strings and 545 * changes the default language. The localized strings are stored as 546 * characters in the XML. 547 * 548 * @param localizationMap the locales and localized strings 549 * @param xml the localizations XML 550 * @param key the name of the localized string, such as "Title" 551 * @param defaultLanguageId the ID of the default language 552 * @return the updated localizations XML 553 */ 554 public String updateLocalization( 555 Map<Locale, String> localizationMap, String xml, String key, 556 String defaultLanguageId); 557 558 /** 559 * Updates the localized string for the system default language in the 560 * localizations XML. The localized strings are stored as characters in the 561 * XML. 562 * 563 * @param xml the localizations XML 564 * @param key the name of the localized string, such as "Title" 565 * @param value the localized string 566 * @return the updated localizations XML 567 */ 568 public String updateLocalization(String xml, String key, String value); 569 570 /** 571 * Updates the localized string for the language in the localizations XML. 572 * The localized strings are stored as characters in the XML. 573 * 574 * @param xml the localizations XML 575 * @param key the name of the localized string, such as "Title" 576 * @param value the localized string 577 * @param requestedLanguageId the ID of the language 578 * @return the updated localizations XML 579 */ 580 public String updateLocalization( 581 String xml, String key, String value, String requestedLanguageId); 582 583 /** 584 * Updates the localized string for the language in the localizations XML 585 * and changes the default language. The localized strings are stored as 586 * characters in the XML. 587 * 588 * @param xml the localizations XML 589 * @param key the name of the localized string, such as "Title" 590 * @param value the localized string 591 * @param requestedLanguageId the ID of the language 592 * @param defaultLanguageId the ID of the default language 593 * @return the updated localizations XML 594 */ 595 public String updateLocalization( 596 String xml, String key, String value, String requestedLanguageId, 597 String defaultLanguageId); 598 599 /** 600 * Updates the localized string for the language in the localizations XML 601 * and changes the default language, optionally storing the localized 602 * strings as CDATA in the XML. 603 * 604 * @param xml the localizations XML 605 * @param key the name of the localized string, such as "Title" 606 * @param value the localized string 607 * @param requestedLanguageId the ID of the language 608 * @param defaultLanguageId the ID of the default language 609 * @param cdata whether to store localized strings as CDATA in the XML 610 * @return the updated localizations XML 611 */ 612 public String updateLocalization( 613 String xml, String key, String value, String requestedLanguageId, 614 String defaultLanguageId, boolean cdata); 615 616 /** 617 * Updates the localized string for the language in the localizations XML 618 * and changes the default language, optionally storing the localized 619 * strings as CDATA in the XML. 620 * 621 * @param xml the localizations XML 622 * @param key the name of the localized string, such as "Title" 623 * @param value the localized string 624 * @param requestedLanguageId the ID of the language 625 * @param defaultLanguageId the ID of the default language 626 * @param cdata whether to store localized strings as CDATA in the XML 627 * @param localized whether there is a localized field 628 * @return the updated localizations XML 629 */ 630 public String updateLocalization( 631 String xml, String key, String value, String requestedLanguageId, 632 String defaultLanguageId, boolean cdata, boolean localized); 633 634 }