001/*
002 * ============================================================================
003 * Copyright © 2002-2021 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.i18n;
019
020import static java.lang.annotation.ElementType.FIELD;
021import static java.lang.annotation.RetentionPolicy.SOURCE;
022import static org.apiguardian.api.API.Status.STABLE;
023
024import java.lang.annotation.Retention;
025import java.lang.annotation.Target;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029
030/**
031 *  <p>{@summary Use this annotation to define the text for a message that has
032 *  to be translated. Texts for UI elements or alike will be defined with the
033 *  annotation
034 *  {@link Text}.}</p>
035 *  <p>The build process will take care of this definition and creates the
036 *  required resource bundle properties files.</p>
037 *  <p>Use this annotation as follows:</p>
038 *  <pre><code>  &#64;Message
039 *  (
040 *      description = "A message",
041 *      translations =
042 *      {
043 *          &#64;Translation( language = "en", text = "This is an English message" ),
044 *          &#64;Translation( language = "de", text = "Dies ist eine Nachricht in Deutsch" )
045 *      }
046 *  )
047 *  public static final int MSG_MessageKey = 1704;</code></pre>
048 *  <p>or</p>
049 *  <pre><code>  &#64;Message
050 *  (
051 *      description = "A message",
052 *      translations =
053 *      {
054 *          &#64;Translation( language = "en", text = "This is an English message" ),
055 *          &#64;Translation( language = "de", text = "Dies ist eine Nachricht in Deutsch" )
056 *      }
057 *  )
058 *  public static final String MSG_MessageKey = "AMessage";</code></pre>
059 *  <p>The value for the constant together with the prefix defined with the
060 *  annotation
061 *  {@link MessagePrefix}
062 *  has to be unique.</p>
063 *
064 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
065 *  @version $Id: Message.java 882 2021-02-27 19:01:25Z tquadrat $
066 *  @since 0.1.0
067 */
068@Retention( SOURCE )
069@Target( FIELD )
070@ClassVersion( sourceVersion = "$Id: Message.java 882 2021-02-27 19:01:25Z tquadrat $" )
071@API( status = STABLE, since = "0.1.0" )
072public @interface Message
073{
074        /*------------*\
075    ====** Attributes **=======================================================
076        \*------------*/
077    /**
078     *  Returns the description for the text.
079     *
080     *  @return The description.
081     */
082    String description();
083
084    /**
085     *  Returns the list of valid translations for the message.
086     *
087     *  @return The translations.
088     */
089    Translation [] translations();
090}
091//  annotation Message
092
093/*
094 *  End of File
095 */