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