crowdfree/README.md

A crowdin compatible tool for translation and localisation of websites and applications

# Crowdfree

A crowdin compatible tool for translation and localisation of websites and applications

## Usage

If your project is set up for it, simply run

    npx crowdfree ./your-project

You can use the 2nd argument to specify the port the internal webserver will listen to.

Once you are in the web interface you simply select the string you want to translate and start typing. Changes are saved to the filesystem as soon as you deselect the input box, allowing for instant updates in for example react apps running in development mode. Changes made on the filesystem are also synchronized back to the web interface. Strings not yet translated into all languages are highlighted in yellow.

![Translation](./frontend/build/translation_1.png)
## Project setup

Crowdfree operates on JSON locale files. The files are expected to be organized in a single locale folder. By default we will look for the first folder called "locale".
Inside the locale folder we expect to find subfolders named after the locale they contain localisations for, ex en, no, es or en-GB, no-NB, en-US etc. You can use any name for the localisations, but for google translate suggestions to work you need to keep to the subset of ISO-639-1 supported by google translate.

File structure:

```
locale
    en
        locale.json
        front page.json
    no
        locale.json
        front page.json
```

Each json file is expected to look like the following:

```JSON
{
    "headertext": "About Crowdfree",
    "bodytext": "Crowdfree is a crowdin compatible tool for translation and localisation of websites and applications."
}
```

Crowdfree will compare the keys in the various locale files and find locale files missing keys and present them to the user with previous translations.
Upon the user entering their translation, crowdfree will add it to the corresponding locale file.

When developing you can add new lines of locale to any file and expect the translators to be able to pick it up without issue.

## Usage of localized strings in your project

We do not yet provide a library for placing the locale strings into your project as that is highly opinionated, but here is a working reference implementation:

your react component:

```Javascript
    import l from "./util/_locale"
    <h3>{l("manual_web_title")}</h3>
```

_locale.jsx

```Javascript
    // Import locale files
    import en from "./../locale/en/manual.json"
    import no from "./../locale/no/manual.json"
    let locale = {
        en, no,
    }
    let debug = false;
    const defaultLocale = "en"
    export default function (key) {
        if (debug) {
            return "<" + key + ">"
        } else {
            if (locale[localStorage.locale || defaultLocale][key] === false || locale[localStorage.locale || defaultLocale][key] === undefined || locale[localStorage.locale || defaultLocale][key] === "") {
                // Look for string in alternate languages
                for (let identifier in locale) {
                    let translation = locale[identifier]
                    if (translation[key] !== undefined) return translation[key]
                }
                if(localStorage.developer) return "<" + key + ">"
                return ""
            } else return locale[localStorage.locale || defaultLocale][key]
        }
    }
```

## Development

Clone the repository

```
git clone https://github.com/danielv123/crowdfree
cd crowdfree
npm install
```

Start the backend at [localhost:3300](http://localhost:3300)

```
npm run backend
```

Start the frontend at [localhost:3000](http://localhost:3000)

```
npm run frontend
```

The frontend will by default connect to the backend running at localhost:3300 when running localy. This can be changed in [`./frontend/.env.development`](./frontend/.env.development)

To plublish updates to npm, run

```
npm publish --dry-run
```

This will run all the tests and create a production build. Once done, it will show a list of all the files included in the final package. Check the files to ensure that nothing sensitive is included. Once satisfied, run ```npm publish```