Skip to content

Commit

Permalink
Improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
André Laugks committed Aug 30, 2024
1 parent 7b751e4 commit 05dfd58
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 158 deletions.
6 changes: 6 additions & 0 deletions .github/workflows/ossrh-release.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Java
uses: actions/setup-java@v4
with:
Expand All @@ -25,6 +26,11 @@ jobs:
gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
gpg-passphrase: GPG_PRIVATE_KEY_PASSPHRASE
cache: 'maven'

- name: Run Tests
run: |
mvn test
- name: Build & Deploy
run: |
mvn -U -B clean deploy -P release
Expand Down
172 changes: 22 additions & 150 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,21 @@

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.

**Table of content**

1. [Version](#a1)
2. [Dependency](#a2)
3. [MessageSource Configuration](#a3)
4. [XLIFF Translation Files](#a4)
5. [Using the MessageSource](#a5)
6. [Full Example](#a6)
7. [Support](#a7)
8. [More Information](#a8)

<a name="a1"></a>
## 1. Versions

| Version | Description |
|:-------------------|:------------------------------------------------------------------------------------------|
| 2.0.0.4-SNAPSHOT | |
| 1.2.1 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.2.1) |
| 1.2.0 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.2.0) |
| 1.1.2 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.2) |
| 1.1.1 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.1) |
| 1.1.0 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.0) |
| 1.0.0 | First public version |
| Version | Description |
|:--------|:----------------------------------------------------------------------------------------------------------------|
| 2.0.0 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/2.0.0) **/ Breaking Change** |
| 1.2.1 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/2.0.0) |
| 1.2.0 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.2.0) |
| 1.1.2 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.2) |
| 1.1.1 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.1) |
| 1.1.0 | [Release notes](https://github.com/alaugks/spring-messagesource-xliff/releases/tag/1.1.0) |
| 1.0.0 | First public version |

[![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/1.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)


<a name="a2"></a>
## 2. Dependency

**Maven**
Expand All @@ -41,18 +28,17 @@ This package provides a [MessageSource](https://docs.spring.io/spring-framework/
<dependency>
<groupId>io.github.alaugks</groupId>
<artifactId>spring-messagesource-xliff</artifactId>
<version>2.0.0.4-SNAPSHOT</version>
<version>2.0.0</version>
</dependency>
```

**Gradle**

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


<a name="a3"></a>
## 3. MessageSource Configuration

The class XliffTranslationMessageSource implements the [MessageSource](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/MessageSource.html) interface.
Expand Down Expand Up @@ -98,7 +84,6 @@ public class MessageConfig {
}
```

<a name="a4"></a>

## 4. XLIFF Translation Files

Expand All @@ -109,19 +94,12 @@ public class MessageConfig {
* In the XLIFF files, the `<target/>` is retrieved in a `<trans-unit/>` (XLIFF 1.2) or `<segment/>` (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)
* 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.&ast;**:
* 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)
* 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 `<file/>` tag are ignored.
* For performance reasons, there is no validation of XLIFF files with an XMLSchema. SAX parser errors are handled by
an [ErrorHandler](https://docs.oracle.com/en/java/javase/17/docs/api/java.xml/org/xml/sax/ErrorHandler.html) and can
be caught with
the [XliffMessageSourceSAXParse-Exceptions](https://github.com/alaugks/spring-messagesource-xliff/tree/main/src/main/java/io/github/alaugks/spring/messagesource/xliff/exception).
* For performance reasons, there is no validation of XLIFF files with an XMLSchema. SAX parser errors are handled by an [ErrorHandler](https://docs.oracle.com/en/java/javase/17/docs/api/java.xml/org/xml/sax/ErrorHandler.html) and can be caught with the [XliffMessageSourceSAXParse-Exceptions](https://github.com/alaugks/spring-messagesource-xliff/tree/main/src/main/java/io/github/alaugks/spring/messagesource/xliff/exception).

### Structure of the Translation Filename

Expand Down Expand Up @@ -188,6 +166,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
```

##### messages_de.xliff

```xml
<?xml version="1.0" encoding="utf-8"?>
<xliff version="1.2"
Expand Down Expand Up @@ -217,6 +196,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
```

##### messages_en-US.xliff

```xml
<?xml version="1.0" encoding="utf-8"?>
<xliff version="1.2"
Expand All @@ -234,6 +214,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
```

##### payment.xliff

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.1" version="2.1"
Expand All @@ -254,6 +235,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
```

##### payment_de.xliff

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.1" version="2.1"
Expand All @@ -274,6 +256,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
```

##### payment_en-US.xliff

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.1" version="2.1"
Expand All @@ -289,7 +272,7 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
</xliff>
```

##### Target value
### Target value

<table>
<thead>
Expand Down Expand Up @@ -353,104 +336,6 @@ Mixing XLIFF versions is possible. Here is an example using XLIFF 1.2 and XLIFF
>
> ***There is no translation for Japanese (`jp`). The default locale translations (`en`) are selected.
<a name="a5"></a>

## 5. Using the MessageSource

With the implementation and use of the MessageSource interface, the translations are also available
in [Thymeleaf](#a5.1), as [Service (Dependency Injection)](#a5.2)
and [Custom Validation Messages](#a5.3). Also in
packages and implementations that use the MessageSource.


<a name="a5.1"></a>
### Thymeleaf

With the configured MessageSource, the translations are available in Thymeleaf. See the example in
the [Full Example](#a6).

```html
<!-- Default domain: messages -->

<!-- "Headline" -->
<h1 th:text="#{headline}"/>
<h1 th:text="#{messages.headline}"/>

<!-- "Postcode" -->
<label th:text="#{postcode}"/>
<label th:text="#{messages.postcode}"/>

<!-- "Your email [email protected] has been registered." -->
<span th:text="#{email-notice('[email protected]')}"/>
<span th:text="#{messages.email-notice('[email protected]')}"/>

<!-- "This is a default message." -->
<span th:text="${#messages.msgOrNull('not-exists-id')} ?: #{default-message}"/>
<span th:text="${#messages.msgOrNull('not-exists-id')} ?: #{messages.default-message}"/>


<!-- Domain: payment -->

<!-- "Payment" -->
<h2 th:text="#{payment.headline}"/>

<!-- "Expiry date" -->
<strong th:text="#{payment.expiry_date}"/>
```

<a name="a5.2"></a>
### Service (Dependency Injection)

The MessageSource can be set via Autowire to access the translations. See the example in
the [Full Example](#a6).

```java
import org.springframework.context.MessageSource;

private final MessageSource messageSource;

// Autowire MessageSource
public MyClass(MessageSource messageSource) {
this.messageSource = messageSource;
}


// Default domain: messages

// "Headline"
this.messageSource.getMessage("headline", null, locale);
this.messageSource.getMessage("messages.headline", null, locale);

// "Postcode"
this.messageSource.getMessage("postcode", null, locale);
this.messageSource.getMessage("messages.postcode", null, locale);

// "Your email [email protected] has been registered."
Object[] args = {"[email protected]"};
this.messageSource.getMessage("email-notice", args, locale);
this.messageSource.getMessage("messages.email-notice", args, locale);

// "This is a default message."
//String defaultMessage = this.messageSource.getMessage("default-message", null, locale);
String defaultMessage = this.messageSource.getMessage("messages.default-message", null, locale);
this.messageSource.getMessage("not-exists-id", null, defaultMessage, locale);


// Domain: payment

// "Payment"
this.messageSource.getMessage("payment.headline", null, locale);

// "Expiry date"
this.messageSource.getMessage("payment.expiry-date", null, locale);
```

<a name="a5.3"></a>
### Custom Validation Messages

The article [Custom Validation MessageSource in Spring Boot](https://www.baeldung.com/spring-custom-validation-message-source) describes how to use custom validation messages.

<a name="a6"></a>

## 6. Full Example

Expand All @@ -464,16 +349,3 @@ Website: https://spring-boot-xliff-example.alaugks.dev
## 7. Support

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

<a name="a8"></a>

## 8. More Information

### MessageSource, Internationalization and Thymeleaf
* [Guide to Internationalization in Spring Boot](https://www.baeldung.com/spring-boot-internationalization)
* [How to Internationalize a Spring Boot Application](https://reflectoring.io/spring-boot-internationalization/)
* [Spring Boot internationalization i18n: Step-by-step with examples](https://lokalise.com/blog/spring-boot-internationalization/)

### Caching
* [A Guide To Caching in Spring](https://www.baeldung.com/spring-cache-tutorial)
* [Implementing a Cache with Spring Boot](https://reflectoring.io/spring-boot-cache/)
2 changes: 1 addition & 1 deletion pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>io.github.alaugks</groupId>
<artifactId>spring-messagesource-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<version>1.0.0</version>
</parent>

<artifactId>spring-messagesource-xliff</artifactId>
Expand Down
14 changes: 7 additions & 7 deletions src/main/java/io/github/alaugks/spring/messagesource/xliff/XliffResourceMessageSource.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
public class XliffResourceMessageSource {

private XliffResourceMessageSource() {
throw new IllegalStateException("XliffResourceMessageSource class");
throw new IllegalStateException(XliffResourceMessageSource.class.toString());
}

public static Builder builder(Locale defaultLocale, String locationPattern) {
Expand Down Expand Up @@ -69,12 +69,12 @@ public MessageSource build() {
);

return CatalogMessageSource
.builder(
xliffCatalog.getTransUnits(),
this.defaultLocale
)
.defaultDomain(this.defaultDomain)
.build();
.builder(
xliffCatalog.getTransUnits(),
this.defaultLocale
)
.defaultDomain(this.defaultDomain)
.build();
}
}
}

0 comments on commit 05dfd58

Please sign in to comment.