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 public Map<Locale, String> getLocalizationMap( 203 PortletRequest portletRequest, String parameter, 204 Map<Locale, String> defaultValues); 205 206 /** 207 * Returns a map of locales and localized strings from the localizations 208 * XML. 209 * 210 * @param xml the localizations XML 211 * @return the locales and localized strings 212 */ 213 public Map<Locale, String> getLocalizationMap(String xml); 214 215 public Map<Locale, String> getLocalizationMap( 216 String xml, boolean useDefault); 217 218 public Map<Locale, String> getLocalizationMap( 219 String bundleName, ClassLoader classLoader, String key, 220 boolean includeBetaLocales); 221 222 /** 223 * Returns a map of locales and localized strings for the given languageIds 224 * and values. 225 * 226 * @param languageIds the languageIds of the localized Strings 227 * @param values the localized strings for the different languageId 228 * @return the map of locales and values for the given parameters 229 */ 230 public Map<Locale, String> getLocalizationMap( 231 String[] languageIds, String[] values); 232 233 /** 234 * Returns the localizations XML for the parameter from the portlet request, 235 * attempting to get data from the preferences container if it is not 236 * available in the portlet request. 237 * 238 * @param preferences the preferences container 239 * @param portletRequest the portlet request 240 * @param parameter the prefix of the parameters containing the localized 241 * strings. Each localization is loaded from a parameter with this 242 * prefix, followed by an underscore, and the language ID. 243 * @return the locales and localized strings 244 */ 245 public String getLocalizationXmlFromPreferences( 246 PortletPreferences preferences, PortletRequest portletRequest, 247 String parameter); 248 249 /** 250 * Returns the localizations XML for the parameter from the portlet request, 251 * attempting to get data from the preferences container if it is not 252 * available in the portlet request. If no localization exists in the 253 * default locale, the default value is used as the localization for it. 254 * 255 * @param preferences the preferences container 256 * @param portletRequest the portlet request 257 * @param parameter the prefix of the parameters containing the localized 258 * strings. Each localization is loaded from a parameter with this 259 * prefix, followed by an underscore, and the language ID. 260 * @param defaultValue the value used as the localization for the default 261 * locale, if no localization exists for it 262 * @return the locales and localized strings 263 */ 264 public String getLocalizationXmlFromPreferences( 265 PortletPreferences preferences, PortletRequest portletRequest, 266 String parameter, String defaultValue); 267 268 /** 269 * Returns the localizations XML for the prefixed parameter from the portlet 270 * request, attempting to get data from the preferences container if it is 271 * not available in the portlet request. If no localization exists for the 272 * the default locale, the default value is used as the localization for it. 273 * 274 * @param preferences the preferences container 275 * @param portletRequest the portlet request 276 * @param parameter the prefix of the parameters containing the localized 277 * strings. Each localization is loaded from a parameter with this 278 * prefix, followed by an underscore, and the language ID. 279 * @param prefix the value used in the request to prefix the parameter name 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, or the 283 * <code>defaultValue</code> if no localization exists 284 */ 285 public String getLocalizationXmlFromPreferences( 286 PortletPreferences preferences, PortletRequest portletRequest, 287 String parameter, String prefix, String defaultValue); 288 289 /** 290 * Returns the localized name in the language. The localized name is the 291 * name, followed by an underscore, and the language ID. 292 * 293 * @param name the name to be localized 294 * @param languageId the ID of the language 295 * @return the localized name for the language 296 */ 297 public String getLocalizedName(String name, String languageId); 298 299 /** 300 * @deprecated As of 6.2.0, replaced by {@link 301 * #getLocalizationMap(PortletRequest, String)} 302 */ 303 @Deprecated 304 public Map<Locale, String> getLocalizedParameter( 305 PortletRequest portletRequest, String parameter); 306 307 /** 308 * Returns the localized preferences key in the language. Generally this is 309 * just the preferences key, followed by an underscore, and the language ID. 310 * 311 * @param key the preferences key 312 * @param languageId the ID of the language 313 * @return the localized preferences key 314 * @deprecated As of 7.0.0, replaced by {@link 315 * #getLocalizedName(String, String)} 316 */ 317 @Deprecated 318 public String getPreferencesKey(String key, String languageId); 319 320 /** 321 * Returns the localized preferences value for the key in the language. The 322 * default language is used if no localization exists for the requested 323 * language. 324 * 325 * @param preferences the preferences container 326 * @param key the preferences key 327 * @param languageId the ID of the language 328 * @return the localized preferences value 329 */ 330 public String getPreferencesValue( 331 PortletPreferences preferences, String key, String languageId); 332 333 /** 334 * Returns the localized preferences value for the key in the language, 335 * optionally using the default language if no localization exists for the 336 * requested language. 337 * 338 * @param preferences the preferences container 339 * @param key the preferences key 340 * @param languageId the ID of the language 341 * @param useDefault whether to use the default language if no localization 342 * exists for the requested language 343 * @return the localized preferences value, or an empty string if 344 * <code>useDefault</code> is <code>false</code> and no localization 345 * exists for the requested language 346 */ 347 public String getPreferencesValue( 348 PortletPreferences preferences, String key, String languageId, 349 boolean useDefault); 350 351 /** 352 * Returns the localized preferences values for the key in the language. The 353 * default language is used if no localization exists for the requested 354 * language. 355 * 356 * @param preferences the preferences container 357 * @param key the preferences key 358 * @param languageId the ID of the language 359 * @return the localized preferences values 360 */ 361 public String[] getPreferencesValues( 362 PortletPreferences preferences, String key, String languageId); 363 364 /** 365 * Returns the localized preferences values for the key in the language, 366 * optionally using the default language if no localization exists for the 367 * requested language. 368 * 369 * @param preferences the preferences container 370 * @param key the preferences key 371 * @param languageId the ID of the language 372 * @param useDefault whether to use the default language if no localization 373 * exists for the requested language 374 * @return the localized preferences values, or an empty string if 375 * <code>useDefault</code> is <code>false</code> and no localization 376 * exists for the requested language 377 */ 378 public String[] getPreferencesValues( 379 PortletPreferences preferences, String key, String languageId, 380 boolean useDefault); 381 382 /** 383 * Returns the localized settings value for the key in the language. The 384 * default language is used if no localization exists for the requested 385 * language. 386 * 387 * @param settings the settings 388 * @param key the settings key 389 * @param languageId the ID of the language 390 * @return the localized settings value 391 */ 392 public String getSettingsValue( 393 Settings settings, String key, String languageId); 394 395 /** 396 * Returns the localized settings value for the key in the language, 397 * optionally using the default language if no localization exists for the 398 * requested language. 399 * 400 * @param settings the settings 401 * @param key the settings key 402 * @param languageId the ID of the language 403 * @param useDefault whether to use the default language if no localization 404 * exists for the requested language 405 * @return the localized settings value. If <code>useDefault</code> is 406 * <code>false</code> and no localization exists for the requested 407 * language, an empty string is returned. 408 */ 409 public String getSettingsValue( 410 Settings settings, String key, String languageId, boolean useDefault); 411 412 /** 413 * Returns the localized settings values for the key in the language. The 414 * default language is used if no localization exists for the requested 415 * language. 416 * 417 * @param settings the settings 418 * @param key the settings key 419 * @param languageId the ID of the language 420 * @return the localized settings values 421 */ 422 public String[] getSettingsValues( 423 Settings settings, String key, String languageId); 424 425 /** 426 * Returns the localized settings values for the key in the language, 427 * optionally using the default language if no localization exists for the 428 * requested language. 429 * 430 * @param settings the settings 431 * @param key the settings key 432 * @param languageId the ID of the language 433 * @param useDefault whether to use the default language if no localization 434 * exists for the requested language 435 * @return the localized settings values. If <code>useDefault</code> is 436 * <code>false</code> and no localization exists for the requested 437 * language, an empty array is returned. 438 */ 439 public String[] getSettingsValues( 440 Settings settings, String key, String languageId, boolean useDefault); 441 442 /** 443 * Removes the localization for the language from the localizations XML. The 444 * localized strings are stored as characters in the XML. 445 * 446 * @param xml the localizations XML 447 * @param key the name of the localized string, such as "Title" 448 * @param requestedLanguageId the ID of the language 449 * @return the localizations XML with the language removed 450 */ 451 public String removeLocalization( 452 String xml, String key, String requestedLanguageId); 453 454 /** 455 * Removes the localization for the language from the localizations XML, 456 * optionally storing the localized strings as CDATA in the XML. 457 * 458 * @param xml the localizations XML 459 * @param key the name of the localized string, such as "Title" 460 * @param requestedLanguageId the ID of the language 461 * @param cdata whether to store localized strings as CDATA in the XML 462 * @return the localizations XML with the language removed 463 */ 464 public String removeLocalization( 465 String xml, String key, String requestedLanguageId, boolean cdata); 466 467 /** 468 * Removes the localization for the language from the localizations XML, 469 * optionally storing the localized strings as CDATA in the XML. 470 * 471 * @param xml the localizations XML 472 * @param key the name of the localized string, such as "Title" 473 * @param requestedLanguageId the ID of the language 474 * @param cdata whether to store localized strings as CDATA in the XML 475 * @param localized whether there is a localized field 476 * @return the localizations XML with the language removed 477 */ 478 public String removeLocalization( 479 String xml, String key, String requestedLanguageId, boolean cdata, 480 boolean localized); 481 482 /** 483 * Sets the localized preferences values for the parameter in the portlet 484 * request. 485 * 486 * @param portletRequest the portlet request 487 * @param preferences the preferences container 488 * @param parameter the prefix of the parameters containing the localized 489 * strings. Each localization is loaded from a parameter with this 490 * prefix, followed by an underscore, and the language ID. 491 * @throws Exception if an exception occurred 492 */ 493 public void setLocalizedPreferencesValues( 494 PortletRequest portletRequest, PortletPreferences preferences, 495 String parameter) 496 throws Exception; 497 498 /** 499 * Sets the localized preferences value for the key in the language. 500 * 501 * @param preferences the preferences container 502 * @param key the preferences key 503 * @param languageId the ID of the language 504 * @param value the localized value 505 * @throws Exception if an exception occurred 506 */ 507 public void setPreferencesValue( 508 PortletPreferences preferences, String key, String languageId, 509 String value) 510 throws Exception; 511 512 /** 513 * Sets the localized preferences values for the key in the language. 514 * 515 * @param preferences the preferences container 516 * @param key the preferences key 517 * @param languageId the ID of the language 518 * @param values the localized values 519 * @throws Exception if an exception occurred 520 */ 521 public void setPreferencesValues( 522 PortletPreferences preferences, String key, String languageId, 523 String[] values) 524 throws Exception; 525 526 /** 527 * Updates the localized string for all the available languages in the 528 * localizations XML for the map of locales and localized strings and 529 * changes the default language. The localized strings are stored as 530 * characters in the XML. 531 * 532 * @param localizationMap the locales and localized strings 533 * @param xml the localizations XML 534 * @param key the name of the localized string, such as "Title" 535 * @param defaultLanguageId the ID of the default language 536 * @return the updated localizations XML 537 */ 538 public String updateLocalization( 539 Map<Locale, String> localizationMap, String xml, String key, 540 String defaultLanguageId); 541 542 /** 543 * Updates the localized string for the system default language in the 544 * localizations XML. The localized strings are stored as characters in the 545 * XML. 546 * 547 * @param xml the localizations XML 548 * @param key the name of the localized string, such as "Title" 549 * @param value the localized string 550 * @return the updated localizations XML 551 */ 552 public String updateLocalization(String xml, String key, String value); 553 554 /** 555 * Updates the localized string for the language in the localizations XML. 556 * The localized strings are stored as characters in the XML. 557 * 558 * @param xml the localizations XML 559 * @param key the name of the localized string, such as "Title" 560 * @param value the localized string 561 * @param requestedLanguageId the ID of the language 562 * @return the updated localizations XML 563 */ 564 public String updateLocalization( 565 String xml, String key, String value, String requestedLanguageId); 566 567 /** 568 * Updates the localized string for the language in the localizations XML 569 * and changes the default language. The localized strings are stored as 570 * characters in the XML. 571 * 572 * @param xml the localizations XML 573 * @param key the name of the localized string, such as "Title" 574 * @param value the localized string 575 * @param requestedLanguageId the ID of the language 576 * @param defaultLanguageId the ID of the default language 577 * @return the updated localizations XML 578 */ 579 public String updateLocalization( 580 String xml, String key, String value, String requestedLanguageId, 581 String defaultLanguageId); 582 583 /** 584 * Updates the localized string for the language in the localizations XML 585 * and changes the default language, optionally storing the localized 586 * strings as CDATA 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 * @param cdata whether to store localized strings as CDATA in the XML 594 * @return the updated localizations XML 595 */ 596 public String updateLocalization( 597 String xml, String key, String value, String requestedLanguageId, 598 String defaultLanguageId, boolean cdata); 599 600 /** 601 * Updates the localized string for the language in the localizations XML 602 * and changes the default language, optionally storing the localized 603 * strings as CDATA in the XML. 604 * 605 * @param xml the localizations XML 606 * @param key the name of the localized string, such as "Title" 607 * @param value the localized string 608 * @param requestedLanguageId the ID of the language 609 * @param defaultLanguageId the ID of the default language 610 * @param cdata whether to store localized strings as CDATA in the XML 611 * @param localized whether there is a localized field 612 * @return the updated localizations XML 613 */ 614 public String updateLocalization( 615 String xml, String key, String value, String requestedLanguageId, 616 String defaultLanguageId, boolean cdata, boolean localized); 617 618 }