Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alaugks/spring-messagesource-xliff

This package provides a MessageSource for using translations from XLIFF files. The package support XLIFF versions 1.2, 2.0 and 2.1.
https://github.com/alaugks/spring-messagesource-xliff

i18n internationalization messagesource spring spring-boot spring-messagesource-xliff spring-translation-xliff thymeleaf translation xliff xliff-files xliff2

Last synced: about 2 months ago
JSON representation

This package provides a MessageSource for using translations from XLIFF files. The package support XLIFF versions 1.2, 2.0 and 2.1.

Awesome Lists containing this project

README 

        
# XLIFF MessageSource for Spring



This package provides a [MessageSource](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/MessageSource.html) for using translations from XLIFF files. The package support XLIFF versions 1.2, 2.0 and 2.1.



[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alaugks_spring-xliff-translation&metric=alert_status)](https://sonarcloud.io/summary/overall?id=alaugks_spring-xliff-translation)

[![Maven Central](https://img.shields.io/maven-central/v/io.github.alaugks/spring-messagesource-xliff.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.alaugks/spring-messagesource-xliff/2.0.0)



## Dependency



### Maven

```xml



    io.github.alaugks

    spring-messagesource-xliff

    2.0.0



```



### Gradle 



```text

implementation group: 'io.github.alaugks', name: 'spring-messagesource-xliff', version: '2.0.0'

```



## MessageSource Configuration



`builder(Locale defaultLocale, String locationPattern)` or


`builder(Locale defaultLocale, List locationPatterns)` (***required***)

* Argument `Locale locale`: Defines the default locale.

* Argument `String locationPattern` | `List locationPatterns`:

  * Defines the pattern used to select the XLIFF files.

  * The package uses the [PathMatchingResourcePatternResolver](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/io/support/PathMatchingResourcePatternResolver.html) to select the XLIFF files. So you can use the supported patterns.

  * Files with the extension `xliff` and `xlf` are filtered from the result list.



`defaultDomain(String defaultDomain)`



* Defines the default domain. Default is `messages`. For more information, see [XLIFF Files](#xliff-files).



### Example



* Default locale is `en`.

* The XLIFF files are stored in `src/main/resources/translations`.



```java

import io.github.alaugks.spring.messagesource.xliff.XliffResourceMessageSource;

import org.springframework.context.MessageSource;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import java.util.Locale;



@Configuration

public class MessageSourceConfig {



    @Bean

    public MessageSource messageSource() {

       return XliffResourceMessageSource

               .builder(

                   Locale.forLanguageTag("en"),

                   "translations/*"

               )

               .build();

    }



}

```



## XLIFF Files



* Translations can be separated into different files (domains). The default domain is `messages`.

* The default domain can be defined.

* Translation files must be stored in the resource folder and have the extension `xliff` or `xlf`.

* In the XLIFF files, the `` is retrieved in a `` (XLIFF 1.2) or `` (XLIFF 2.*).

  * **XLIFF 1.2**:

    * If the attribute `resname` does not exist, the attribute `id` is used to determine the identifier.

    * Documentation identifier: [XLIFF 1.2](http://docs.oasis-open.org/xliff/v1.2/xliff-profile-html/xliff-profile-html-1.2.html#General_Identifiers)

  * **XLIFF 2.***:

    * The attribute `id` is optional by standard in XLIFF 2.*. However, this package requires the `id` on a translation unit.

    * Documentation identifier: [XLIFF 2.0](https://docs.oasis-open.org/xliff/xliff-core/v2.0/csprd01/xliff-core-v2.0-csprd01.html#segment) and [XLIFF 2.1](https://docs.oasis-open.org/xliff/xliff-core/v2.1/os/xliff-core-v2.1-os.html#segment)

* All attributes in the `` tag are ignored.  

* For performance reasons, there is no validation of XLIFF files with an XMLSchema.

* SAX parser errors are handled by an [ErrorHandler](src/main/java/io/github/alaugks/spring/messagesource/xliff/exception/SaxErrorHandler.java).



### Structure of the Translation Filename



```

# Default language

.xlf    // _.xlf also works.



# Domain + Language

[-_].xlf



# Domain + Language + Region

[-_][-_].xlf

```



### Example with XLIFF Files



* Default domain is `messages`.

* Default locale is `en` without region.

* Translations are provided for the locale `en`, `de` and `en-US`.



```

[resources]

     |-[translations]

             |-messages.xliff           // Default domain and default language. messages_en.xliff also works.

             |-messages_de.xliff

             |-messages_en-US.xliff

             |-payment.xliff            // Default language. payment_en.xliff also works.

             |-payment_de.xliff

             |-payment_en-US.xliff     

```  



#### XLIFF Files



Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF 2.1.



##### messages.xliff



```xml



    

        

            

                Headline

                Headline

            

            

                Postcode

                Postcode

            

        

    



```



##### messages_de.xliff



```xml



    

        

            

                Headline

                Überschrift

            

            

                Postcode

                Postleitzahl

            

        

    



```



##### messages_en-US.xliff



```xml



    

        

            

                Postcode

                Zip code

            

        

    



```



##### payment.xliff



```xml



    

        

            

                Payment

                Payment

            

            

                Expiry date

                Expiry date

            

        

    



```



##### payment_de.xliff



```xml



    

        

            

                Payment

                Zahlung

            

            

                Expiry date

                Ablaufdatum

            

        

    



```



##### payment_en-US.xliff



```xml



    

        

            

                Expiry date

                Expiration date

            

        

    



```



#### Target value



The behaviour of resolving the target value based on the code is equivalent to the ResourceBundleMessageSource or ReloadableResourceBundleMessageSource.



  

  

    id (code)

    en

    en-US

    de

    jp***

  

  

  

  

    headline*
messages.headline

    Headline

    Headline**

    Überschrift

    Headline

  

  

    postcode*
messages.postcode

    Postcode

    Zip code

    Postleitzahl

    Postcode

  

  

    payment.headline

    Payment

    Payment**

    Zahlung

    Payment

  

  

    payment.expiry_date

    Expiry date

    Expiration date

    Ablaufdatum

    Expiry date

  

  



> *Default domain is `messages`.

>

> **Example of a fallback from Language_Region (`en-US`) to Language (`en`). The `id` does not exist in `en-US`, so it tries to select the translation with locale `en`.

> 

> ***There is no translation for Japanese (`jp`). The default locale translations (`en`) are selected.



## Full Example



A Full Example using Spring Boot, mixing XLIFF 1.2 and XLIFF 2.1 translation files:



Repository: https://github.com/alaugks/spring-messagesource-xliff-example


Website: https://spring-boot-xliff-example.alaugks.dev



## Support



If you have questions, comments or feature requests please use the [Discussions](https://github.com/alaugks/spring-xliff-translation/discussions) section.