/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

package org.apache.james.imap.api.display;

/**
 * Localizes text for display.
 */
public interface Localizer {

    /**
     * <p>Localizes the given text for display.</p>
     * <p>
     * It is recommended that {@link HumanReadableText#getKey()} is 
     * used as key. {@link HumanReadableText#getParameters()} may (optionally) 
     * be used for substitution into a parameterised text.
     * </p>
     * <p>
     * Implementators are free to use any appropriate algorithm 
     * to determine which locale should be used. A client application
     * may request a particular Locale based on it's local settings. 
     * This preference SHOULD be made available (by the caller) 
     * through {@link Locales#getClientPreference()}.
     * In addition, user data may contain localization preferences. These
     * SHOULD be made available (by the caller) through {@link Locales#getUserPreferences()}.
     * </p><p>
     * {@link HumanReadableText#getDefaultValue()} provides a simple, standard english phrase. 
     * It is recommended that implementors use this value when a suitable localisation
     * cannot be discovered.
     * </p>
     * @param text describes the text requiring localisation, not null
     * @param locales describes preferences, not null
     * @return localized message not null
     */
    public String localize(HumanReadableText text, Locales locales);
}
