/*
 * Copyright (C) VSPLF Software Foundation (VSF), the origin author or authors.
 *
 * Licensed 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.vsplf.i18n;

import java.util.Locale;
import java.util.Map;

/**
 * The TranslatorBuilder for easier usage of Translator. <br />
 * TranslatorBuilder must be thread-safe.
 * For example:
 * <pre>
 *  TranslatorBuilder tb = TranslatorFactory.getTranslatorBuilder();
 *  String message = tb._("hello {0}").
 *                      messageArguments(new String[]{"VSPLF"}).
 *                      message();
 * </pre>
 *
 * @author <a href="http://hoatle.net">hoatle (hoatlevan at gmail dot com)</a>
 * @since Mar 22, 2012
 */
public interface TranslatorBuilder {
  /**
   * Sets the message pattern for translating.
   *
   * @param messagePattern the message pattern.
   * @return the translator builder.
   */
  TranslatorBuilder _(String messagePattern);

  /**
   * Sets the message arguments as an array of objects.
   *
   * @param messageArguments an array of objects for message arguments.
   * @return the translator builder.
   */
  TranslatorBuilder messageArguments(Object[] messageArguments);

  /**
   * Sets the message arguments as a map of objects with key as named argument.
   *
   * @param messageArguments a map of objects for message arguments.
   * @return the translator builder.
   */
  TranslatorBuilder messageArguments(Map<String, Object> messageArguments);

  /**
   * Sets the specific locale to translate a message pattern.
   *
   * @param locale the specified locale.
   * @return the translator builder.
   */
  TranslatorBuilder locale(Locale locale);

  /**
   * Translates the message pattern with all the available context information.
   *
   * @return the translated message.
   */
  String message();
}

@@ -774,19 +774,16 @@
 . %3Cbr /%3E
-%0A *
  Transla
@@ -800,16 +800,19 @@
  must be
+%0A *
  thread-
@@ -816,19 +816,16 @@
 ad-safe.
-%0A *
  For exa
@@ -1459,16 +1459,25 @@
 f object
+ argument
 s.%0A   *%0A
@@ -1649,32 +1649,284 @@
 ageArguments);%0A%0A
+  /**%0A   * Appends a message argument with the type of Object to the array of object arguments.%0A   *%0A   * @param messageArgument an object argument%0A   * @return the translator builder.%0A   */%0A  TranslatorBuilder appendArgument(Object messageArgument);%0A%0A
   /**%0A   * Sets 
@@ -2181,32 +2181,424 @@
 ageArguments);%0A%0A
+  /**%0A   * Appends a message argument with the type of Map%3CString, Object%3E to the array of message%0A   * arguments.%0A   *%0A   * @param keyName              the key name associated with message argument value.%0A   * @param messageArgumentValue the message argument value.%0A   * @return the translator builder.%0A   */%0A  TranslatorBuilder appendArgument(String keyName, Object messageArgumentValue);%0A%0A
   /**%0A   * Sets 

Update TranslatorBuilder APIs: add appendArgument method