# stranslator

**Repository Path**: sauntor/stranslator

## Basic Information

- **Project Name**: stranslator
- **Description**: A most lightweight library for translating you application to the local languages.
- **Primary Language**: Scala
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2017-04-12
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Stranslator
A most lightweight library for translating you application to the local languages.

### The XML format for translation file
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<translator>
    <message>
        <from>This is the original message!</from>
        <to>
            <!-- the translation for chinese -->
            <zh>这是原始文本！</zh>
            <!-- the translation for traditional chinese(Hong Kong) -->
            <zh_HK>這是原始文本！</zh_HK>
        </to>
    </message>
</translator>
```
### Usage
1. Add `Stranslator` to your project
```sbtshell
libraryDependencies += "com.lingcreative" %% "stranslator" % "1.1.0"
```

2. Code sample
```scala
import translator._

val translator = Translator()
val locale = new Locale("zh", "CN")
implicit val context = SimpleTranslatorContext(translator, Seq(locale))

val welcome = ${"Hello, Sauntor! Welcome to China!"}
```
If you create a translation file which is located in `l10n/translator.xml`(within the class path) with the flowing content:
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<translator>
    <message>
        <from>Hello, Sauntor! Welcome to China!</from>
        <to>
            <zh_CN>适然，你好！欢迎来到中国！</zh_CN>
        </to>
    </message>
</translator>
```
The `welcome` would be:
`适然，你好！欢迎来到中国！`
###### Notice
1. the line feed(`\n`) after the beginning and before the ending tag of `from`, `locale`s  (in `to` tag, i.e. `locale` stands for `<zh_CN>` and `</zh_CN>`), will be ignored.
2. you can break one line into multiple lines by putting an `\ ` to the end of the line(and the leading space is ignored and the space after `\ ` will be preserved).
For example:
```xml
<translator>
    <message>
        <from>
            Hello, \
            Jack! I'm waiting \
            for you!
        </from>
        <to>
            <zh>捷克，你来了。\
            我已经等你好久了！
            </zh>
        </to>
    </message>
</translator>
```
The code above is equal to:
```xml
<translator>
    <message>
        <from>Hello, Jack! I'm waiting for you!</from>
        <to><zh>捷克，你来了。我已经等你好久了！</zh></to>
    </message>
</translator>
```
3. The default location to load translations from is `l10n/translator.xml`, i.e.
```scala
val translator = Translator()
```
Is equal to:
```scala
val translator = Translator("cp://l10n/translator.xml")
// Or to this:
//val translator = Translator("l10n/translator.xml")
```
4. You can `include` another xml for translations by `<include>`tag :
```xml
<translator>
    <include>http://example.com:9000/some/app/l10n/translations.xml</include>
</translator>
```
> The `<include>` tag **does not** support **relative path**, i.e. you can't include a resource like `../some/other/module.xml`.

### About the `stranslator.Translator`
It's the core API for translating. You can initialize it with an URL. An class path resource will start with "cp://" (no prefix is identical to it too),
or an external resource on a **Web Server** with the corresponding uri pattern(i.e. http://example.com/l10n/demo-app.xml).

### Enjoy it! :tea: