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