Metadata-Version: 2.4
Name: lime-translate
Version: 0.0.1a0
Summary: Lime-translate is a Python library designed to improve compatibility between Limesurvey and computer-assisted translation (CAT) software.
Author-email: Jean-Baptiste Bertrand <jean-baptiste.bertrand@univ-amu.fr>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.huma-num.fr/jbertrand/lime-translate
Project-URL: Issues, https://gitlab.huma-num.fr/jbertrand/lime-translate/issues
Keywords: limesurvey,translation,conversion
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=6.0.0
Dynamic: license-file

# Lime-translate 0.0.1a0

Lime-translate is a Python library designed to improve compatibility between Limesurvey and computer-assisted translation (CAT) software. Currently, it can convert Limesurvey files (LSS) to the XLIFF format used by computer-assisted translation software, and reintegrate the translated file into the original LSS file.

# Current features

- conversion from LSS to XLIFF
- reintegrating a translated XLIFF file into a LSS file

This is an alpha version, so use it at your own risks!

# Installation

`pip install lime-translate`

# Motivation

Limesurvey is an open-source statistical survey web application. It already offers a translation interface for multilingual surveys, but this translation interface is quite rudimentary compared to the features offered by modern computer-assisted translation tools (OmegaT, weblate, etc). In addition, Limesurvey currently does not offer an export format directly compatible with these CAT tools.

The `lime-translate` package is meant to fill this current compatibility gap between Limesurvey and computer-assisted translation tools.

# Usage example

Bob creates a survey in Limesurvey, in English. He wants to have this questionnaire translated to French by a professional translator, Alice, who generally uses computer-assisted translation (CAT) software. As the survey is particularly complex, using CAT software would be much more quick and effective than using the native Limesurvey "quick translation" interface.

Bob creates an export of his survey to the LSS format. However, he and Alice quickly realize that this format is not compatible with the CAT software Alice uses. Therefore, Bob converts the LSS file to the CAT-friendly XLIFF format, using the lime-translate package:


```
import lime_translate as lt
lss_file_path = "./bob_survey/source_english.lss"
xliff_files = lt.lss_to_xliff(lss_file_path=lss_file_path)
target_fr_path = "./bob_survey/translation_files/to_translate/english_to_french.xliff"
with open(target_fr_path, "wb") as f:
    f.write(xliff_files["fr"])
```

Bob then transmits the new "english_to_french.xliff" file to Alice for translation.

Alice translates the XLIFF file in her CAT tool. Once it's done, she transmits the translated XLIFF file back to Bob. Bob then integrates the translation into the original LSS file, using the following code:

```
import lime_translate as lt
original_LSS_path = "./bob_survey/source_english.lss"
xliff_file_path = "./bob_survey/translation_files/translated/english_to_french.xliff"
updated_lss = lt.xliff_to_LSS(xliff_file_path, original_LSS_path)
with open("./bob_survey/translated/bilingual_en_fr.lss", "wb") as f:
    f.write(updated_lss)
```

Tadam! Bob will then be able to immediately import the resulting translated survey file ("bilingual_en_fr.lss") into Limesurvey.

# Exporting an LSS file from Limesurvey

To ensure your LSS file will work seamlessly with `lime-translate`, before [exporting the LSS file](https://www.limesurvey.org/manual/Display/Export_survey) from Limesurvey, you must [add your target language to the "additional languages" section](https://www.limesurvey.org/manual/Multilingual_survey) in the Limesurvey admin interface.


# Limitations, compatibility with Limesurvey versions, etc.

While it is planned to support more recent versions of Limesurvey, the package is currently only compatible with LSS files exported from Limesurvey 3.x.

The only supported export format is XLIFF, while the package is also planned to support other formats in the future.

This is an alpha version, initially developed as an experiment for a one-time translation project. While it worked quite well for this specific project, it has not been tested extensively. The package is also missing a proper documentation, though a relatively straightforward usage example is provided above.

Any feedback is welcome, but use it at your own risks!
