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 /** 320 * @deprecated As of 6.2.0, replaced by {@link 321 * #getLocalizationMap(PortletRequest, String)} 322 */ 323 @Deprecated 324 public Map<Locale, String> getLocalizedParameter( 325 PortletRequest portletRequest, String parameter); 326 327 public Map<Locale, String> getMap(LocalizedValuesMap localizedValuesMap); 328 329 /** 330 * Returns the localized preferences key in the language. Generally this is 331 * just the preferences key, followed by an underscore, and the language ID. 332 * 333 * @param key the preferences key 334 * @param languageId the ID of the language 335 * @return the localized preferences key 336 * @deprecated As of 7.0.0, replaced by {@link #getLocalizedName(String, 337 * String)} 338 */ 339 @Deprecated 340 public String getPreferencesKey(String key, String languageId); 341 342 /** 343 * Returns the localized preferences value for the key in the language. The 344 * default language is used if no localization exists for the requested 345 * language. 346 * 347 * @param preferences the preferences container 348 * @param key the preferences key 349 * @param languageId the ID of the language 350 * @return the localized preferences value 351 */ 352 public String getPreferencesValue( 353 PortletPreferences preferences, String key, String languageId); 354 355 /** 356 * Returns the localized preferences value for the key in the language, 357 * optionally using the default language if no localization exists for the 358 * requested language. 359 * 360 * @param preferences the preferences container 361 * @param key the preferences key 362 * @param languageId the ID of the language 363 * @param useDefault whether to use the default language if no localization 364 * exists for the requested language 365 * @return the localized preferences value, or an empty string if 366 * <code>useDefault</code> is <code>false</code> and no localization 367 * exists for the requested language 368 */ 369 public String getPreferencesValue( 370 PortletPreferences preferences, String key, String languageId, 371 boolean useDefault); 372 373 /** 374 * Returns the localized preferences values for the key in the language. The 375 * default language is used if no localization exists for the requested 376 * language. 377 * 378 * @param preferences the preferences container 379 * @param key the preferences key 380 * @param languageId the ID of the language 381 * @return the localized preferences values 382 */ 383 public String[] getPreferencesValues( 384 PortletPreferences preferences, String key, String languageId); 385 386 /** 387 * Returns the localized preferences values for the key in the language, 388 * optionally using the default language if no localization exists for the 389 * requested language. 390 * 391 * @param preferences the preferences container 392 * @param key the preferences key 393 * @param languageId the ID of the language 394 * @param useDefault whether to use the default language if no localization 395 * exists for the requested language 396 * @return the localized preferences values, or an empty string if 397 * <code>useDefault</code> is <code>false</code> and no localization 398 * exists for the requested language 399 */ 400 public String[] getPreferencesValues( 401 PortletPreferences preferences, String key, String languageId, 402 boolean useDefault); 403 404 /** 405 * Returns the localized settings value for the key in the language. The 406 * default language is used if no localization exists for the requested 407 * language. 408 * 409 * @param settings the settings 410 * @param key the settings key 411 * @param languageId the ID of the language 412 * @return the localized settings value 413 */ 414 public String getSettingsValue( 415 Settings settings, String key, String languageId); 416 417 /** 418 * Returns the localized settings value for the key in the language, 419 * optionally using the default language if no localization exists for the 420 * requested language. 421 * 422 * @param settings the settings 423 * @param key the settings key 424 * @param languageId the ID of the language 425 * @param useDefault whether to use the default language if no localization 426 * exists for the requested language 427 * @return the localized settings value. If <code>useDefault</code> is 428 * <code>false</code> and no localization exists for the requested 429 * language, an empty string is returned. 430 */ 431 public String getSettingsValue( 432 Settings settings, String key, String languageId, boolean useDefault); 433 434 /** 435 * Returns the localized settings values for the key in the language. The 436 * default language is used if no localization exists for the requested 437 * language. 438 * 439 * @param settings the settings 440 * @param key the settings key 441 * @param languageId the ID of the language 442 * @return the localized settings values 443 */ 444 public String[] getSettingsValues( 445 Settings settings, String key, String languageId); 446 447 /** 448 * Returns the localized settings values for the key in the language, 449 * optionally using the default language if no localization exists for the 450 * requested language. 451 * 452 * @param settings the settings 453 * @param key the settings key 454 * @param languageId the ID of the language 455 * @param useDefault whether to use the default language if no localization 456 * exists for the requested language 457 * @return the localized settings values. If <code>useDefault</code> is 458 * <code>false</code> and no localization exists for the requested 459 * language, an empty array is returned. 460 */ 461 public String[] getSettingsValues( 462 Settings settings, String key, String languageId, boolean useDefault); 463 464 public String getXml(LocalizedValuesMap localizedValuesMap, String key); 465 466 /** 467 * Removes the localization for the language from the localizations XML. The 468 * localized strings are stored as characters in the XML. 469 * 470 * @param xml the localizations XML 471 * @param key the name of the localized string, such as "Title" 472 * @param requestedLanguageId the ID of the language 473 * @return the localizations XML with the language removed 474 */ 475 public String removeLocalization( 476 String xml, String key, String requestedLanguageId); 477 478 /** 479 * Removes the localization for the language from the localizations XML, 480 * optionally storing the localized strings as CDATA in the XML. 481 * 482 * @param xml the localizations XML 483 * @param key the name of the localized string, such as "Title" 484 * @param requestedLanguageId the ID of the language 485 * @param cdata whether to store localized strings as CDATA in the XML 486 * @return the localizations XML with the language removed 487 */ 488 public String removeLocalization( 489 String xml, String key, String requestedLanguageId, boolean cdata); 490 491 /** 492 * Removes the localization for the language from the localizations XML, 493 * optionally storing the localized strings as CDATA in the XML. 494 * 495 * @param xml the localizations XML 496 * @param key the name of the localized string, such as "Title" 497 * @param requestedLanguageId the ID of the language 498 * @param cdata whether to store localized strings as CDATA in the XML 499 * @param localized whether there is a localized field 500 * @return the localizations XML with the language removed 501 */ 502 public String removeLocalization( 503 String xml, String key, String requestedLanguageId, boolean cdata, 504 boolean localized); 505 506 /** 507 * Sets the localized preferences values for the parameter in the portlet 508 * request. 509 * 510 * @param portletRequest the portlet request 511 * @param preferences the preferences container 512 * @param parameter the prefix of the parameters containing the localized 513 * strings. Each localization is loaded from a parameter with this 514 * prefix, followed by an underscore, and the language ID. 515 * @throws Exception if an exception occurred 516 */ 517 public void setLocalizedPreferencesValues( 518 PortletRequest portletRequest, PortletPreferences preferences, 519 String parameter) 520 throws Exception; 521 522 /** 523 * Sets the localized preferences value for the key in the language. 524 * 525 * @param preferences the preferences container 526 * @param key the preferences key 527 * @param languageId the ID of the language 528 * @param value the localized value 529 * @throws Exception if an exception occurred 530 */ 531 public void setPreferencesValue( 532 PortletPreferences preferences, String key, String languageId, 533 String value) 534 throws Exception; 535 536 /** 537 * Sets the localized preferences values for the key in the language. 538 * 539 * @param preferences the preferences container 540 * @param key the preferences key 541 * @param languageId the ID of the language 542 * @param values the localized values 543 * @throws Exception if an exception occurred 544 */ 545 public void setPreferencesValues( 546 PortletPreferences preferences, String key, String languageId, 547 String[] values) 548 throws Exception; 549 550 /** 551 * Updates the localized string for all the available languages in the 552 * localizations XML for the map of locales and localized strings and 553 * changes the default language. The localized strings are stored as 554 * characters in the XML. 555 * 556 * @param localizationMap the locales and localized strings 557 * @param xml the localizations XML 558 * @param key the name of the localized string, such as "Title" 559 * @param defaultLanguageId the ID of the default language 560 * @return the updated localizations XML 561 */ 562 public String updateLocalization( 563 Map<Locale, String> localizationMap, String xml, String key, 564 String defaultLanguageId); 565 566 /** 567 * Updates the localized string for the system default language in the 568 * localizations XML. The localized strings are stored as characters in the 569 * XML. 570 * 571 * @param xml the localizations XML 572 * @param key the name of the localized string, such as "Title" 573 * @param value the localized string 574 * @return the updated localizations XML 575 */ 576 public String updateLocalization(String xml, String key, String value); 577 578 /** 579 * Updates the localized string for the language in the localizations XML. 580 * The localized strings are stored as characters in the XML. 581 * 582 * @param xml the localizations XML 583 * @param key the name of the localized string, such as "Title" 584 * @param value the localized string 585 * @param requestedLanguageId the ID of the language 586 * @return the updated localizations XML 587 */ 588 public String updateLocalization( 589 String xml, String key, String value, String requestedLanguageId); 590 591 /** 592 * Updates the localized string for the language in the localizations XML 593 * and changes the default language. The localized strings are stored as 594 * characters in the XML. 595 * 596 * @param xml the localizations XML 597 * @param key the name of the localized string, such as "Title" 598 * @param value the localized string 599 * @param requestedLanguageId the ID of the language 600 * @param defaultLanguageId the ID of the default language 601 * @return the updated localizations XML 602 */ 603 public String updateLocalization( 604 String xml, String key, String value, String requestedLanguageId, 605 String defaultLanguageId); 606 607 /** 608 * Updates the localized string for the language in the localizations XML 609 * and changes the default language, optionally storing the localized 610 * strings as CDATA in the XML. 611 * 612 * @param xml the localizations XML 613 * @param key the name of the localized string, such as "Title" 614 * @param value the localized string 615 * @param requestedLanguageId the ID of the language 616 * @param defaultLanguageId the ID of the default language 617 * @param cdata whether to store localized strings as CDATA in the XML 618 * @return the updated localizations XML 619 */ 620 public String updateLocalization( 621 String xml, String key, String value, String requestedLanguageId, 622 String defaultLanguageId, boolean cdata); 623 624 /** 625 * Updates the localized string for the language in the localizations XML 626 * and changes the default language, optionally storing the localized 627 * strings as CDATA in the XML. 628 * 629 * @param xml the localizations XML 630 * @param key the name of the localized string, such as "Title" 631 * @param value the localized string 632 * @param requestedLanguageId the ID of the language 633 * @param defaultLanguageId the ID of the default language 634 * @param cdata whether to store localized strings as CDATA in the XML 635 * @param localized whether there is a localized field 636 * @return the updated localizations XML 637 */ 638 public String updateLocalization( 639 String xml, String key, String value, String requestedLanguageId, 640 String defaultLanguageId, boolean cdata, boolean localized); 641 642 }