= TranslationService
: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.

Provides translated versions of the various elements within the framework's metamodel: service and object classes, properties, collections, actions, action parameters; and also to translate business rule (disable/valid) messages, and exceptions. These translations provide for both singular and plural forms.

As such, this domain service is the cornerstone of the framework's i18n support.

== API

[source,java]
.TranslationService.java
----
interface TranslationService {
  String translate(TranslationContext context, String text)     // <.>
  String translate(TranslationContext context, String singularText, String pluralText, int num)     // <.>
  Mode getMode()     // <.>
  TranslationService identity()     // <.>
}
----

<.> xref:#translate_TranslationContext_String[translate(TranslationContext, String)]
+
--
Return a translation of the text, in the locale of the "current user".
--
<.> xref:#translate_TranslationContext_String_String_int[translate(TranslationContext, String, String, int)]
+
--
Return a translation of either the singular or the plural text, dependent on the `num` parameter, in the locale of the "current user".
--
<.> xref:#getMode_[getMode()]
+
--
Whether this implementation is operating in read or in write mode.
--
<.> xref:#identity_[identity()]
+
--
Can be used as fallback in the absence of a xref:refguide:applib:index/services/i18n/TranslationService.adoc[TranslationService] implementation. Acts as a text pass-through, not translating anything.
--

== Members

[#translate_TranslationContext_String]
=== translate(TranslationContext, String)

Return a translation of the text, in the locale of the "current user".

The mechanism to determine the locale is implementation-specific.

[#translate_TranslationContext_String_String_int]
=== translate(TranslationContext, String, String, int)

Return a translation of either the singular or the plural text, dependent on the `num` parameter, in the locale of the "current user".

The mechanism to determine the locale is implementation-specific.

[#getMode_]
=== getMode()

Whether this implementation is operating in read or in write mode.

If in read mode, then the translations are expected to be present. In such cases, the _#translate(TranslationContext, String) translate_ _#translate(TranslationContext, String, String, int) method_ s should be _lazily_ called, if only because there will (most likely) need to be a session in progress (such that the locale of the current user can be determined).

If in write mode, then the implementation is saving translation keys, and will always return the untranslated translation. In such cases, the _#translate(TranslationContext, String) translate_ _#translate(TranslationContext, String, String, int) method_ s should be _eagerly_ called such that all pathways are exercised..

[#identity_]
=== identity()

Can be used as fallback in the absence of a xref:refguide:applib:index/services/i18n/TranslationService.adoc[TranslationService] implementation. Acts as a text pass-through, not translating anything.

include::hooks/TranslationService_010-implementation.adoc[]

include::hooks/TranslationService_020-examples-and-usage.adoc[]
