Title: I18n
Notice:    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.


[TOC]

***

# Introduction

## Type-safe messages

### Simple use-case

The following implementation is the minimal effort to use type-safe messages (which are hardcoded in this case).

**Simple type-safe message**

    @MessageBundle
    public interface SimpleMessage
    {
        @MessageTemplate("Welcome to DeltaSpike")
        String welcomeToDeltaSpike();
    }

The following implementation uses the key `welcome_to_deltaspike` to do a lookup in the default message bundle. The default bundle has the same name as the interface (but .properties instead of .java (/.class) as file extension).

**Internationalized type-safe message**

    @MessageBundle
    public interface SimpleMessage
    {
        @MessageTemplate("{welcome_to_deltaspike}")
        String welcomeToDeltaSpike();
    }

    org.apache.deltaspike.example.message.SimpleMessage

    ->

    org/apache/deltaspike/example/message/SimpleMessage.properties
    org/apache/deltaspike/example/message/SimpleMessage_en.properties
    org/apache/deltaspike/example/message/SimpleMessage_de.properties
    ...

    //content (as usual in message bundle files:
    welcome_to_deltaspike=Welcome to DeltaSpike

The following implementation uses the key `welcome_to_deltaspike` to do a lookup in a custom message bundle known by `CustomMessageResolver`.

**Internationalized type-safe message**

    @MessageBundle
    @MessageContextConfig(messageResolver = CustomMessageResolver.class)
    public interface SimpleMessage
    {
        @MessageTemplate("{welcome_to_deltaspike}")
        String welcomeToDeltaSpike();
    }

`@MessageContextConfig` allows to provide a custom `MessageResolver`, `MessageInterpolator` and `LocaleResolver`.

The following implementation shows the usage of an internationalized simple type-safe message.

**Internationalized type-safe message with parameter/s**

    @MessageBundle
    @MessageContextConfig(messageInterpolator = CustomMessageInterpolator.class)
    public interface SimpleMessage
    {
        //in the message bundle: welcome_to=Welcome to %s

        @MessageTemplate("{welcome_to}")
        String welcomeTo(String name);
    }

    //...
    public class MyBean
    {
        @Inject
        private SimpleMessage messages;

        public String welcomeToDeltaSpike
        {
            return this.messages.welcomeTo("DeltaSpike");
        }
    }

## Dynamic Message Builder

### Creating message instances

The following implementation creates an instance of `Message` for the key `hello`. The final text will be resolved and interpolated lazily. Later on it might be supported to provide a different `MessageContext` via `#toString(MessageContext)` like it is in MyFaces CODI right now.

[TODO]

### Customizing the message context

#### MessageResolver

A message-resolver is responsible for creating the message-text based on the message-descriptor (key or inline-text), the current locale (and in some cases the message-payload).
(The supported format e.g. if it's required to escape a key, if inline-text is supported,... depends on the concrete implementation.)
In case of a message-key, the message-resolver has to transform it to the message-text by looking it up in a message source like a resource-bundle.

**Configuration of a message-resolver**

[TODO]

The result of a `MessageResolver` is the message-text. The text might contain placeholders which are processed by a `MessageInterpolator`

#### MessageInterpolator

A `MessageInterpolator` replaces the placeholders in a message-text with the arguments of the message.

**Configuration of a message-interpolator**

[TODO]

#### LocaleResolver

A locale resolver provides the current locale. The locale is e.g. used to by a `MessageResolver` to choose the correct language for the message-text.

**Configuration of a locale-resolver**

[TODO]