diff --git a/docs/_docs/guides/000-user-roles-overview.md b/docs/_docs/guides/000-user-roles-overview.md new file mode 100644 index 0000000000..beee88bd43 --- /dev/null +++ b/docs/_docs/guides/000-user-roles-overview.md @@ -0,0 +1,94 @@ +--- +layout: doc +title: "User Roles & Permissions" +date: 2025-02-04 10:00:00 -0800 +categories: guides +permalink: /docs/guides/user-roles-overview/ +--- + +{{ site.mojito_green }} uses roles to control what you can see and do. This guide explains each role and what applies to you. + +## Roles at a glance + +| Role | Who you are | What you can do | +|------|-------------|-----------------| +| **User** | Basic access | View repositories, workbench, branches, screenshots. Search and browse. No edits. | +| **Translator** | Translation team member | Everything User can do, plus edit translations in Workbench for your assigned locales. Export, import, share searches. | +| **Project Manager (PM)** | Coordinates translation work | Everything Translator can do, plus create/import/cancel project requests, manage screenshots, manage users. | +| **Admin** | System administrator | Everything PM can do, plus AI Translate, database monitoring, Box integration. | + +--- + +## For Translators + +**You can:** +- Search and browse text units in the [Workbench]({{ site.url }}/docs/guides/workbench/) +- Add and edit translations for locales assigned to you +- Export search results (CSV/JSON) for offline work or reporting +- Import translations from CSV or JSON files +- Share search links with colleagues +- View [project requests]({{ site.url }}/docs/guides/project-request/) (read-only) +- View [branches]({{ site.url }}/docs/guides/branching/) and branch statistics +- View screenshots (legacy page) and upload screenshots (new dropzone) + +**You cannot:** +- Create or import project requests (PM or Admin only) +- Add or edit screenshots in the legacy screenshot dashboard (PM or Admin only) +- Access AI Translate (Admin only) +- Access database monitoring (Admin only) +- Manage users (PM or Admin only) +- Configure Box integration (Admin only) + +If you can't edit a translation, or if you get an error when importing, your role or locale assignment may not include that permission. Ask your project manager or admin. + +--- + +## For Project Managers + +**You can do everything Translators can, plus:** +- Create translation and review [project requests]({{ site.url }}/docs/guides/project-request/) +- Import and re-import completed projects +- Cancel project requests +- Add and manage screenshots in the [legacy screenshot dashboard]({{ site.url }}/docs/guides/branching/#collecting-screenshots) +- Manage users (add, update roles) via **Settings → User Management** + +**You cannot:** +- Access [AI Translate]({{ site.url }}/docs/guides/ai-translate/) (Admin only) +- Access [database monitoring]({{ site.url }}/docs/refs/monitoring/) (Admin only) +- Configure Box integration (Admin only) + +--- + +## For Admins + +**You can do everything Project Managers can, plus:** +- Use [AI Translate]({{ site.url }}/docs/guides/ai-translate/) to batch-translate repositories with AI +- Access [database latency monitoring]({{ site.url }}/docs/refs/monitoring/) (User menu → Monitoring) +- Configure [Box integration]({{ site.url }}/docs/guides/integrating-with-box/) for project requests (Settings → Box Integration) + +The **AI Translate** link appears in the main navigation only for Admins. The **Monitoring** link appears in your user menu (top right) only for Admins. + +--- + +## Feature quick reference + +| Feature | User | Translator | PM | Admin | +|---------|------|------------|-----|-------| +| Workbench: search, view | ✓ | ✓ | ✓ | ✓ | +| Workbench: edit translations | — | ✓ (assigned locales) | ✓ | ✓ | +| Workbench: export, import, share | — | ✓ | ✓ | ✓ | +| Project requests: view | ✓ | ✓ | ✓ | ✓ | +| Project requests: create, import, cancel | — | — | ✓ | ✓ | +| Screenshots: view, upload (dropzone) | ✓ | ✓ | ✓ | ✓ | +| Screenshots: add/edit (legacy) | — | — | ✓ | ✓ | +| Branches: view | ✓ | ✓ | ✓ | ✓ | +| User management | — | — | ✓ | ✓ | +| AI Translate | — | — | — | ✓ | +| Monitoring | — | — | — | ✓ | +| Box integration (Settings) | — | — | — | ✓ | + +--- + +## Locale assignment (Translators) + +Translators can only edit translations for locales they are assigned to. If you have "translate all locales" permission, you can edit any locale. Otherwise, you'll only see edit controls for your assigned locales. Ask your admin or PM to update your locale assignment if you need access to more languages. diff --git a/docs/_docs/guides/001-getting-started.md b/docs/_docs/guides/001-getting-started.md index db0c10b3b1..fb0ef15f88 100644 --- a/docs/_docs/guides/001-getting-started.md +++ b/docs/_docs/guides/001-getting-started.md @@ -5,7 +5,7 @@ categories: guides permalink: /docs/guides/getting-started/ --- -For this guide, we use [Brew](http://brew.sh/) to install {{ site.mojito_green }} Webapp and CLI (`Java 1.8` is required). +For this guide, we use [Brew](http://brew.sh/) to install {{ site.mojito_green }} Webapp and CLI (`Java 21` is required). ### Setup and install @@ -59,7 +59,7 @@ Check in the Workbench that the string was added and is untranslated. Try adding Finally, this generates the updated localized files with the new translation. -![update localized filwa](./images/update-localized.gif) +![update localized files](./images/update-localized.gif) ### What's next? diff --git a/docs/_docs/guides/002-install.md b/docs/_docs/guides/002-install.md index ef768c7c1c..0a733a240c 100644 --- a/docs/_docs/guides/002-install.md +++ b/docs/_docs/guides/002-install.md @@ -27,12 +27,12 @@ Run the CLI with: Default configuration location: - usr/local/etc/mojito/cli/application.properties - usr/local/etc/mojito/webapp/application.properties + /usr/local/etc/mojito/cli/application.properties + /usr/local/etc/mojito/webapp/application.properties ### Using Executable Jars -`Java 1.8` is required. Executable Jars can be downloaded in the [release section](https://github.com/box/mojito/releases/). +`Java 1.8` is required for this deprecated version. For current releases (master branch), see [Installation and Setup (Spring Boot 3)]({{ site.url }}/docs/guides/install-springboot3/) which requires `Java 21`. Executable Jars can be downloaded in the [release section](https://github.com/box/mojito/releases/). Run the Webapp with: @@ -54,7 +54,7 @@ One simple solution is to add an `application.properties` next to the `jar`. To The server provides an entry point to fetch a `bash` script that downloads the latest CLI from the server and create a bash wrapper to easily run the CLI. -It can be called with a one liner to make the bash command available rigth away in the current console. Replace +It can be called with a one liner to make the bash command available right away in the current console. Replace `http://localhost:8080` with the actual URL if needed. ```bash diff --git a/docs/_docs/guides/002-install_springboot3.md b/docs/_docs/guides/002-install_springboot3.md index 6eb1fdde8f..3956d009e6 100644 --- a/docs/_docs/guides/002-install_springboot3.md +++ b/docs/_docs/guides/002-install_springboot3.md @@ -37,7 +37,7 @@ One simple solution is to add an `application.properties` next to the `jar`. To The server provides an entry point to fetch a `bash` script that downloads the latest CLI from the server and create a bash wrapper to easily run the CLI. -It can be called with a one liner to make the bash command available rigth away in the current console. Replace +It can be called with a one liner to make the bash command available right away in the current console. Replace `http://localhost:8080` with the actual URL if needed. ```bash @@ -74,7 +74,7 @@ server.forward-headers-strategy=native ## Setup The default setup comes with `HSQL` in-memory database, database authentication and runs on port `8080`. -For production, `MySQL` should be setup. Different types of [authentication](/docs/guides/authentication-springboot2/) are +For production, `MySQL` should be setup. Different types of [authentication]({{ site.url }}/docs/guides/authentication-springboot3/) are available too. On the first Webapp startup, a user: `admin/ChangeMe` is created. This can be customized with configuration, @@ -138,7 +138,7 @@ l10n.org.quartz.dataSource.myDS.maxConnections=12 l10n.org.quartz.dataSource.myDS.validationQuery=select 1 ``` -Note that `utf8mb4` setup has been tested on MySQL `5.7`. The server will probably needs some configuration too, for +Note that `utf8mb4` setup has been tested on MySQL `8`. The server will probably need some configuration too, for example by editing `my.cnf` (if installed with brew: `/usr/local/etc/my.cnf`) with something like: ```properties @@ -159,7 +159,7 @@ max_allowed_packet = 256M If using a older version of MySQL, there is a [known issue](https://github.com/box/mojito/issues/120) when creating the schema. One workaround is to use `utf8` instead `utf8mb4` but it has its limitation in term of character support. -We recommand to run both MySQL and the Java service using `UTC` timezone (or a least make sure they both the same timezone). To set +We recommend running both MySQL and the Java service using `UTC` timezone (or a least make sure they both the same timezone). To set `UTC` as default use the following: ```properties diff --git a/docs/_docs/guides/004-string-extraction.md b/docs/_docs/guides/004-string-extraction.md index 6f2665ef4e..85a9bc7c80 100644 --- a/docs/_docs/guides/004-string-extraction.md +++ b/docs/_docs/guides/004-string-extraction.md @@ -42,7 +42,7 @@ This extracts the two strings from the source resource file and stores them in ` mojito push -r MyRepo -s /home/explicitPath/ProjectA -By default, {{ site.mojito_green }} searches source resource files from current working directory and its sub-directories. If you have your source resource file in a specific directory, you can use `-s` parameter to telll {{ site.mojito_green }} where to find source resource files. The above example extracts strings `strings.properties` from `ProjectA` directory using relative path and explicit path. +By default, {{ site.mojito_green }} searches source resource files from current working directory and its sub-directories. If you have your source resource file in a specific directory, you can use `-s` parameter to tell {{ site.mojito_green }} where to find source resource files. The above example extracts strings `strings.properties` from `ProjectA` directory using relative path and explicit path. ### Specific Source File Type @@ -52,7 +52,7 @@ By default, {{ site.mojito_green }} searches source resource files from current By default, {{ site.mojito_green }} processes all supported source resource files in the working directory. If your working directory has many types of source resource files and if you want to only process specific type, you can use `-ft` parameter. The above example only extracts strings from Java Properties file. -Available file types are `XLIFF`, `XCODE_XLIFF`, `MAC_STRING`, `MAC_STRINGSDICT`, `ANDROID_STRINGS`, `PROPERTIES`, `PROPERTIES_NOBASENAME`, `PROPERTIES_JAVA`, `RESW`, `RESX`, `PO`, `XTB`, `CSV`, `JS`, `JSON` and `TS`. +Available file types are `XLIFF`, `XCODE_XLIFF`, `MAC_STRING`, `MAC_STRINGSDICT`, `ANDROID_STRINGS`, `PROPERTIES`, `PROPERTIES_NOBASENAME`, `PROPERTIES_JAVA`, `RESW`, `RESX`, `PO`, `XTB`, `CSV`, `CSV_ADOBE_MAGENTO`, `JS`, `JSON`, `JSON_NOBASENAME`, `CHROME_EXT_JSON`, `FORMATJS_JSON_NOBASENAME`, `VSCODE_EXTENSION_JSON`, `I18NEXT_PARSER_JSON`, `TS`, `YAML`, and `HTML_ALPHA`. The difference between `PROPERTIES` and `PROPERTIES_NOBASENAME` is that the source resource file of `PROPERTIES_NOBASENAME` has source locale name as the file name. For example, `strings.properties` vs. `en.properties`. `PROPERTIES_JAVA` is for the JAVA properties file in ISO_8859-1 encoding with escaped unicode characters. @@ -64,7 +64,7 @@ The `XCODE_XLIFF` is for the xliff files generated by Xcode. mojito push -r MyRepo -sl en-US -ft PROPERTIES_NOBASENAME -{{ site.mojito_green }} uses `en` as source locale by default. {{ site.mojito_green }} uses soure locale to identity source resource files from localized resource files. For example, if you have `en.properties` and `en-US.properties` in your working directory, `en.properties` is used as source resource file by default and `en-US.properties` is considered as localized resource file. The above example overrides the default source locale and use `en-US` as source locale using `-sl` parameter. You must use `-sl` parameter with `-ft` parameter. +{{ site.mojito_green }} uses `en` as source locale by default. {{ site.mojito_green }} uses source locale to identify source resource files from localized resource files. For example, if you have `en.properties` and `en-US.properties` in your working directory, `en.properties` is used as source resource file by default and `en-US.properties` is considered as localized resource file. The above example overrides the default source locale and use `en-US` as source locale using `-sl` parameter. You must use `-sl` parameter with `-ft` parameter. ### Specific Source File Regex diff --git a/docs/_docs/guides/005-generating-localized-files.md b/docs/_docs/guides/005-generating-localized-files.md index ad2a4affeb..3569887e94 100644 --- a/docs/_docs/guides/005-generating-localized-files.md +++ b/docs/_docs/guides/005-generating-localized-files.md @@ -5,7 +5,7 @@ categories: guides permalink: /docs/guides/generating-localized-files/ --- -In this guide, we use `mojito-cli` to generate localized resource files. Translations in the repository are used to generate localized resource files. This process is called `pull` in {{ site.mojito }} because translations are "pulled" from {{ site.mojito_green }} to generate localized resource files. +In this guide, we use `mojito-cli` to generate localized resource files. Translations in the repository are used to generate localized resource files. This process is called `pull` in {{ site.mojito_green }} because translations are "pulled" from {{ site.mojito_green }} to generate localized resource files. ### Pull @@ -89,7 +89,7 @@ By default, {{ site.mojito_green }} searches source resource files from current {{ site.mojito_green }} processes all supported source resource files in the working directory by default. If your working directory has many types of source resource files and if you want to only process specific type, you can use `-ft` parameter. The above example only generates localized files for Java Properties file. -Available file types are `XLIFF`, `XCODE_XLIFF`, `MAC_STRING`, `MAC_STRINGSDICT`, `ANDROID_STRINGS`, `PROPERTIES`, `PROPERTIES_NOBASENAME`, `PROPERTIES_JAVA`, `RESW`, `RESX`, `PO`, `XTB`, `CSV`, `JS`, `JSON` and `TS`. +Available file types are `XLIFF`, `XCODE_XLIFF`, `MAC_STRING`, `MAC_STRINGSDICT`, `ANDROID_STRINGS`, `PROPERTIES`, `PROPERTIES_NOBASENAME`, `PROPERTIES_JAVA`, `RESW`, `RESX`, `PO`, `XTB`, `CSV`, `CSV_ADOBE_MAGENTO`, `JS`, `JSON`, `JSON_NOBASENAME`, `CHROME_EXT_JSON`, `FORMATJS_JSON_NOBASENAME`, `VSCODE_EXTENSION_JSON`, `I18NEXT_PARSER_JSON`, `TS`, `YAML`, and `HTML_ALPHA`. The difference between `PROPERTIES` and `PROPERTIES_NOBASENAME` is that the source resource file of `PROPERTIES_NOBASENAME` has source locale name as the file name. For example, `strings.properties` vs. `en.properties`. `PROPERTIES_JAVA` is for the JAVA properties file in ISO_8859-1 encoding with escaped unicode characters. @@ -101,7 +101,7 @@ The `XCODE_XLIFF` is for the xliff files generated by Xcode. mojito pull -r MyRepo -sl en-US -ft PROPERTIES_NOBASENAME -By default, {{ site.mojito_green }} uses `en` as source locale. {{ site.mojito_green }} uses soure locale to identity source resource files from localized resource files. For example, if you have `en.properties` and `en-US.properties` in your working directory, `en.properties` is used as source resource file by default and `en-US.properties` is considered as localized resource file. The above example overrides the default source locale and use `en-US` as source locale using `-sl` parameter. You must use `-sl` parameter with `-ft` parameter. +By default, {{ site.mojito_green }} uses `en` as source locale. {{ site.mojito_green }} uses source locale to identify source resource files from localized resource files. For example, if you have `en.properties` and `en-US.properties` in your working directory, `en.properties` is used as source resource file by default and `en-US.properties` is considered as localized resource file. The above example overrides the default source locale and use `en-US` as source locale using `-sl` parameter. You must use `-sl` parameter with `-ft` parameter. @@ -115,4 +115,4 @@ Let's say you have the following source resource files in working directory. You can use regular expression to filter source resource files to generate localized resource files from. The following example only generates localized resource for release-1 related files using `-sr` parameter for regular expression. - mojito push -r MyRepo -sr "^(release-1).*$" + mojito pull -r MyRepo -sr "^(release-1).*$" diff --git a/docs/_docs/guides/006-workbench.md b/docs/_docs/guides/006-workbench.md index a7b7086f10..02c8af5494 100644 --- a/docs/_docs/guides/006-workbench.md +++ b/docs/_docs/guides/006-workbench.md @@ -10,6 +10,8 @@ Workbench in {{ site.mojito_green }} is a place where you can search and edit al Use Workbench to fix bugs, communicate context to translation teams and manage global terminology changes. Translators and reviewers can also work directly in Workbench. +> **Who can use the Workbench:** Everyone can search and view. **Translators**, **Project Managers**, and **Admins** can edit translations (Translators only for their assigned locales). Export, Import, and Share are available to Translators, PMs, and Admins. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/) for details. + ## Searching ![Workbench Search](./images/WorkbenchSearch.png) @@ -34,9 +36,11 @@ Use Workbench to fix bugs, communicate context to translation teams and manage g - Filter by status - `All` - includes all text units regardless of their status - `Translated` - includes all text units that have a translation - - `Needs translation` - includes all text units with no translation and all text units marked as `needs translation` - - `Needs review` - includes all text units marked as 'needs review' - - `Rejected` - includes text units marked 'rejected' + - `Untranslated` - includes text units with no translation + - `Needs Translation` - includes text units marked for translation (e.g. previously translated but sent for retranslation) + - `Needs Review` - includes text units marked as 'needs review' + - `Rejected` - includes text units marked 'rejected' (won't be included in localized files) + - `Accepted` - includes text units that are approved and not rejected - Filter by presence in product - `Used` - includes text units that are still used in your products - `Unused` - includes legacy text units that have been removed from product or modified @@ -69,7 +73,7 @@ Warning! Do not remove translation from the translation field. If you do so, you ![Mark as need translation](./images/MarkAsNeedTranslation.gif) -Select the text unit in the workbench and click `Status`. In the Status pop-up, select `Needs translation`. +Select the text unit in the workbench and click `Status`. In the Status pop-up, select `Needs Translation`. You can also leave a comment on the text unit to let translators know, to what they should pay particular attention. @@ -80,7 +84,7 @@ When you are done, click `Save`. The text unit will be included in your next tra ![Mark as need review](./images/MarkAsNeedReview.gif) If you have a review step in your translation workflow, you will want to export a review project. Only text units that are marked as `needs review` will be included in your review project. -To mark a text unit for review, select it in the workbench and click on `Status`. Select `Needs review`. +To mark a text unit for review, select it in the workbench and click on `Status`. Select `Needs Review`. You can also leave a comment on the text unit to let reviewers know, to what they should pay particular attention. @@ -90,7 +94,7 @@ When you are done, click `Save`. The text unit will be included in your next rev ![Mark string as final](./images/MarkAsFinal.gif) -When you are happy with your text unit, you can mark it as final. To mark a text unit as final, select it in the workbench and click on Status. Select Accepted. When you are done, click Save. Final text units will not get included into any translation or review projects. If you change your mind later, you can always mark the unit to be included into translation or review projects (see points 2 and 3). +When you are happy with your text unit, you can mark it as final. To mark a text unit as final, select it in the workbench and click on `Status`. Select `Accepted`. When you are done, click `Save`. Final text units will not get included into any translation or review projects. If you change your mind later, you can always mark the unit to be included into translation or review projects (see points 2 and 3). ## Bulk-managing text units @@ -100,5 +104,46 @@ When you are happy with your text unit, you can mark it as final. To mark a text Making global changes to strings is made easy. {{ site.mojito_green }} allows you to select multiple strings across pages. Additionally, you can also select all strings on a particular page. To do so, click on the selection dropdown. Then click on `Select all in page`. If you want to clear all selections on a particular page, click on `Clear all in page`. All selections on the page will be cleared. Your selections on other pages will be preserved. + If you need to clear all selections across all pages, click on `Clear all`. +## Exporting search results + +> **Who can export:** Translators, Project Managers, and Admins. + +You can export your current search results to CSV or JSON for offline work, reporting, or backup. Click **Export search results** in the Workbench toolbar. + +1. Choose the format (CSV or JSON). +2. Select which fields to include (e.g. source, target, repository name, asset path, status). +3. Optionally enable **Generate a separate file for each locale** to split results by locale. +4. Set a maximum number of records (default 10,000). +5. Click **Export** to download. + +The export uses your current search filters (repositories, locales, status, etc.). Use this to create files for external tools or to share data with colleagues who work outside {{ site.mojito_green }}. + +## Importing translations + +> **Who can import:** Translators, Project Managers, and Admins. + +You can import translations from a CSV or JSON file—for example, from an export or from an external translation tool. Click **Import translations** in the Workbench toolbar. + +1. Upload a CSV or JSON file (drag and drop or click to browse). +2. Required columns: `repositoryName`, `assetPath`, `targetLocale`, either `tmTextUnitId` or `name`, and `target`. +3. Optional columns: `branchId`, `comment`, `targetComment`, `status`, `includedInLocalizedFile`, `doNotTranslate`, and others. +4. Review any validation errors. Rows with errors are skipped. +5. Click **Import** to apply the changes. + +Use the **Download template** link to get a CSV template with the required columns. The import runs in the background; you can close the modal once it starts. + +## Sharing searches + +> **Who can share:** Translators, Project Managers, and Admins. + +You can create a shareable link that opens the Workbench with your current search (repositories, locales, filters, etc.). Click **Share this search** in the Workbench toolbar. + +1. The modal shows a URL with a unique link. +2. Click **Copy** to copy the URL to your clipboard. +3. Share the link with colleagues. When they open it, they see the same search you had. + +This is useful for pointing reviewers to specific strings, sharing filtered views with translators, or bookmarking complex searches. + diff --git a/docs/_docs/guides/007-project-request.md b/docs/_docs/guides/007-project-request.md index 73af7409c2..8c353660b7 100644 --- a/docs/_docs/guides/007-project-request.md +++ b/docs/_docs/guides/007-project-request.md @@ -8,6 +8,8 @@ permalink: /docs/guides/project-request/ {{ site.mojito_green }} allows you to create project packages for your translation teams. You can create them at the `Project Requests` page. +> **Who can use Project Requests:** Everyone can view projects. **Project Managers** and **Admins** can create, import, re-import, and cancel requests. Translators and Users can only view. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + ### Request a translation project ![Request translation](./images/TranslationRequest.gif) diff --git a/docs/_docs/guides/008-managing-locales.md b/docs/_docs/guides/008-managing-locales.md index 3bf119cac4..456013f76b 100644 --- a/docs/_docs/guides/008-managing-locales.md +++ b/docs/_docs/guides/008-managing-locales.md @@ -23,15 +23,14 @@ We use `mojito-cli` to configure locales in a repository. Locales can be config By default, all locales configured in the repository are required to be fully translated. These locales get automatically included in the translation requests. -You can configure the locales to be partially translated. English in United Kingdom (en-GB) is a good example because most of the strings do not need to be "translated". Source strings can be used as-is in most cases and only some strings that are specific to English in United Kingdom need to be overriden. +You can configure the locales to be partially translated. English in United Kingdom (en-GB) is a good example because most of the strings do not need to be "translated". Source strings can be used as-is in most cases and only some strings that are specific to English in United Kingdom need to be overriden. In this sense, en-GB is an inherited locale. That is, it inherits +most of its strings from the parent locale, which in this example, is en-US. ```bash mojito repo-update -n MyRepo -l "(en-GB)" es-ES fr-FR ja-JP zh-CN zh-TW ``` -The above example adds English in United Kingdome (en-GB) to `MyRepo` repository. Having parenthesis around the locale excludes the locale from being fully translated. - - +The above example adds English in United Kingdom (en-GB) to `MyRepo` repository. Having parenthesis around the locale excludes the locale from being fully translated. ### Locale Inheritance @@ -44,7 +43,8 @@ mojito repo-update -n MyRepo -l "(fr-CH)->fr-FR" fr-FR ja-JP zh-CN zh-TW The above example makes French in Switzerland (fr-CH) the child locale of French in France (fr-FR). -Note that the partially translated locales are displayed in grey color in locales list. +Note that the partially translated locales are displayed in grey color in locales list. The parent locale for partially +translated locales is implicitly the source locale, which is often en or en-US. That is, it is equivalent to writing "(en-GB)->en-US". ![Partially Translated Locales](./images/partially-translated-locales.png) diff --git a/docs/_docs/guides/009-integrity-checkers.md b/docs/_docs/guides/009-integrity-checkers.md index 71799506a0..268b543b05 100644 --- a/docs/_docs/guides/009-integrity-checkers.md +++ b/docs/_docs/guides/009-integrity-checkers.md @@ -5,7 +5,7 @@ categories: guides permalink: /docs/guides/integrity-checkers/ --- -In this guide, let's go over the integrity checkers in {{ site.mojito_green }} in detail. Integrity checkers perform checks on the translations against the source strings and reject the translations with errors. This prevents translations with errors from being used in localized resource files which can lead to build faiilure or errors in application. +In this guide, let's go over the integrity checkers in {{ site.mojito_green }} in detail. Integrity checkers perform checks on the translations against the source strings and reject the translations with errors. This prevents translations with errors from being used in localized resource files which can lead to build failure or errors in application. We use `mojito-cli` to configure integrity checkers in a repository. Integrity checkers can be configured when you create and update repository in {{ site.mojito_green }} with `-it` parameter. You can set integrity checker for each file extension of resource files. For example, `-it resw:COMPOSITE_FORMAT,xlf:PRINTF_LIKE`. @@ -19,13 +19,28 @@ We use `mojito-cli` to configure integrity checkers in a repository. Integrity ### Available Integrity Checkers | Integrity Checker | Recommended File Extensions     | File Format | -|:---------------------------------------|:------------------------------- ---------------|:-------------------------------------| +|:---------------------------------------|:-----------------------------------------------|:-------------------------------------| | COMPOSITE_FORMAT | resw, resx | RESW, RESX | | MESSAGE_FORMAT | properties | Java Properties | -| PRINTF_LIKE | xml, strings, | Android Strings, iOS/Mac Strings, | -| SIMPLE_PRINTF_LIKE | | | -| WHITESPACE | | | -| TRAILING_WHITESPACE     | | | +| MESSAGE_FORMAT_DOUBLE_BRACES | vue, hbs, mustache | Strings with `{{` placeholders | +| PRINTF_LIKE | xml, strings | Android Strings, iOS/Mac Strings | +| PRINTF_LIKE_IGNORE_PERCENTAGE_AFTER_BRACKETS | | | +| PRINTF_LIKE_VARIABLE_TYPE | | | +| PRINTF_LIKE_ADD_PARAMETER_SPECIFIER | | | +| SIMPLE_PRINTF_LIKE | | Placeholders like %1, %2 | +| FLUENT | ftl | Fluent localization | +| WHITESPACE | | Leading and trailing whitespace | +| TRAILING_WHITESPACE | | Trailing whitespace only | +| HTML_TAG | html | HTML content | +| ELLIPSIS | | Ellipsis characters | +| BACKQUOTE | | Backtick characters | +| EMPTY_TARGET_NOT_EMPTY_SOURCE | | Empty translation when source has content | +| MARKDOWN_LINKS | | Markdown link syntax | +| PYTHON_FPRINT | py | Python f-string format | +| EMAIL | eml | Email format | +| URL | | URL format | +| FORBIDS_CONTROL_CHARACTERS | | Control characters | +| MISC_AI_TRANSLATE | | AI translation validation | ### Composite Format Integrity Checker @@ -97,14 +112,14 @@ The translation gets rejected if any placeholder in the source string is missing Whitespace integrity checker validates that the leading and trailing whitespaces in the source string exist in the translation. -The translation gets rejected if any leading or traingling whitespace in the source string is missing in the translation. +The translation gets rejected if any leading or trailing whitespace in the source string is missing in the translation. | Source String | Translation | Checker | |:-------------------------------------------------------|:----------------------------------------------------------------------|:------------------| | [space]Hello %@![newline] | [space]¡Hola %@![newline] | OK | | [space]%1$d files and %2$d folders | %1$d fichiers et %2$s dossiers | FAIL missing leading space | | %1$d files and %2$d folders[newline] | %1$d fichiers et %2$s dossiers | FAIL missing trailing newline | -| [space]%1 files and %2 folders[newline] | [newline]%1 fichiers et %2 dossiers[space]   | FAIL modified leading and trailing whitepsace | +| [space]%1 files and %2 folders[newline] | [newline]%1 fichiers et %2 dossiers[space]   | FAIL modified leading and trailing whitespace | @@ -113,12 +128,12 @@ The translation gets rejected if any leading or traingling whitespace in the sou Trailing whitespace integrity checker validates that the trailing whitespaces in the source string exist in the translation. -The translation gets rejected if any traingling whitespace in the source string is missing in the translation. +The translation gets rejected if any trailing whitespace in the source string is missing in the translation. | Source String | Translation | Checker | |:-------------------------------------------------------------------|:----------------------------------------------------------------------|:------------------| | Hello %@![space][newline] | ¡Hola %@![space][newline] | OK | -| %1$d files and %2$d folders[space] | %1$d fichiers et %2$s dossiers | FAIL missing trailng space | +| %1$d files and %2$d folders[space] | %1$d fichiers et %2$s dossiers | FAIL missing trailing space | | %1$d files and %2$d folders[newline] | %1$d fichiers et %2$s dossiers | FAIL missing trailing newline | | %1 files and %2 folders[space][newline]   | %1 fichiers et %2 dossiers[newline][space]   | FAIL modified trailing whitespaces | diff --git a/docs/_docs/guides/010-import-localized-files.md b/docs/_docs/guides/010-import-localized-files.md index 4f72e02a8d..ffd4e5ee69 100644 --- a/docs/_docs/guides/010-import-localized-files.md +++ b/docs/_docs/guides/010-import-localized-files.md @@ -17,7 +17,7 @@ repository from scratch following a bad manipulation. If starting with a new repository, the `push` command must be run first since `import` doesn't process the source files. Skip following step if working on an existing project: ```bash -mojito repo-create -n MyRepo -l fr-FR,ja-JP +mojito repo-create -n MyRepo -l fr-FR ja-JP mojito push -r MyRepo ``` @@ -30,10 +30,10 @@ mojito import -r MyRepo The major addition to the `push`/`pull` options is `--status-equal-target` that allows you to define the behavior of the import when the "translation" is -the same the source string. +the same as the source string. -It lets you skip the import or mark the string with special status (approved, -translation needed, review needed) +It lets you skip the import or mark the string with special status (`APPROVED`, +`TRANSLATION_NEEDED`, `REVIEW_NEEDED`, or `SKIPPED`). ```bash mojito import -r MyRepo --status-equal-target SKIPPED diff --git a/docs/_docs/guides/011-plural-support.md b/docs/_docs/guides/011-plural-support.md index 53e88cb9c1..54ab6c13d9 100644 --- a/docs/_docs/guides/011-plural-support.md +++ b/docs/_docs/guides/011-plural-support.md @@ -27,7 +27,7 @@ opens the workbench with all different plural forms. Depending on the locale, the forms shown are customized. For example, while English has 2 forms (singular and plural), Japanese has a single form and Russian 4 forms. -The 2 forms shown for English in the the workbench: +The 2 forms shown for English in the workbench: ![create demo repository](./images/wb-english.png) diff --git a/docs/_docs/guides/012-git-blame-info.md b/docs/_docs/guides/012-git-blame-info.md index b548c588c3..5b2b39d049 100644 --- a/docs/_docs/guides/012-git-blame-info.md +++ b/docs/_docs/guides/012-git-blame-info.md @@ -9,7 +9,7 @@ When you use `Mojito`, you may need additional information about the text units commit introduced them. This information about the text unit can be extracted using the `git-blame` command from the `mojito-cli`. This command -uses the [git-blame](https://git-scm.com/docs/git-blame) command to extract the the information about the text unit. +uses the [git-blame](https://git-scm.com/docs/git-blame) command to extract the information about the text unit. Depending on the file type, the `blame` command can be run on the lines of the source resource files or read in the usage locations from the resource files to use to get the `blame` information from the code base. @@ -37,7 +37,7 @@ The command will run `git blame` on the file `res/values/strings.xml` and save t The command can also be run on specified file types using the `-ft` parameter - mojito git-blame -r MyRepo -ft FileType + mojito git-blame -r MyRepo -ft PO ### Blame with usages diff --git a/docs/_docs/guides/013-branching.md b/docs/_docs/guides/013-branching.md index 12146eef7b..8ee4fe904e 100644 --- a/docs/_docs/guides/013-branching.md +++ b/docs/_docs/guides/013-branching.md @@ -7,6 +7,8 @@ permalink: /docs/guides/branching/ {{ site.mojito_green }} supports `branching` by simply adding an extra parameter to the `push` command. +> **Who can use branches and screenshots:** Everyone can view the branch dashboard. Adding screenshots in the legacy screenshot dashboard requires **Project Manager** or **Admin** role. The new Screenshots page (upload dropzone) is available to everyone. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + Using branches is transparent to other tasks and won't be noticed unless voluntarily using it to process [pull requests](#process-pull-request--diff) and interacting with the [branch dashboard](#branch-dashboard). @@ -105,7 +107,7 @@ when the commits are merged into the "master" branch and it takes some time to g When working in a fast paced environment where deployments can happen multiple times a day. It is likely that features will be pushed in production without being fully localized, leading to poor experience for international users. It -can also create inefficencies in the testing process. +can also create inefficiencies in the testing process. If releases are gated or less frequent, it is easier to wait for strings to be ready before publishing the feature but last minute changes may still happen. @@ -183,10 +185,13 @@ the actual strings. #### Collecting screenshots -Providing context to translators is key for having quality translations. In addition to adding comments in the code base, -{{ site.mojito_green }} provides a simple way to collect screenshots for strings in a branch. +Providing context to translators is key for having quality translations. {{ site.mojito_green }} offers two ways to work with screenshots: + +**Legacy screenshot dashboard** (Screenshots link when "legacy" is enabled, or Branches → Screenshot button): Select one or multiple text units and click `Add screenshot` to attach images. **Project Managers** and **Admins** can add and edit screenshots; others can view. + +**Screenshots page** (main navigation → Screenshots): A drag-and-drop page where you upload images (.png, .jpg, .jpeg). Each upload returns a reference like `s:550e8400-e29b-41d4-a716-446655440000`. Copy this reference and use it in source comments or asset metadata to link screenshots to text units. Everyone can upload; no repository or locale selection is needed. -Once in the dashboard, it is possible to select one or multiple text units and then click on the `Add screenshot` button. +Once in the legacy dashboard, it is possible to select one or multiple text units and then click on the `Add screenshot` button. ![Search branch by name](./images/add-screenshot.gif) @@ -213,7 +218,7 @@ mojito pull -r MyRepo hello = Bonjour ``` -It is not possbible to create a branch that has a differente translation `Bonjour!` (adding the missing exclamation mark). +It is not possible to create a branch that has a different translation `Bonjour!` (adding the missing exclamation mark). Branches may have different source strings (the `push` command as the branch parameter) but not translations (`pull` command doesn't have any branch parameter). @@ -221,7 +226,7 @@ If this is not acceptable, an alternative is to clone the repository instead but and no tool are provided to merge branches easily. Note that modifying the name/context/comment of an existing string in the code base leads to the creation of a new -string. So it is tottally safe to change a placeholder in a branch while keeping the same string `name`. In that case +string. So it is totally safe to change a placeholder in a branch while keeping the same string `name`. In that case the translation won't be shared since the string are different. For example, the `master` branch contains following file: diff --git a/docs/_docs/guides/014-ai-translate.md b/docs/_docs/guides/014-ai-translate.md new file mode 100644 index 0000000000..3fce10a42f --- /dev/null +++ b/docs/_docs/guides/014-ai-translate.md @@ -0,0 +1,70 @@ +--- +layout: doc +title: "AI Translate" +date: 2025-02-04 10:00:00 -0800 +categories: guides +permalink: /docs/guides/ai-translate/ +--- + +AI Translate lets you batch-translate a repository using an AI model. {{ site.mojito_green }} sends source strings to the configured AI service and imports the translations back. + +> **Who can use AI Translate:** Admins only. The **AI Translate** link appears in the main navigation only if you have the Admin role. Translators and Project Managers do not see this page. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + +## When to use it + +Use AI Translate when you want to: +- Get an initial pass of translations for a new locale +- Fill in missing translations at scale +- Experiment with different models or prompts (dry run first) + +Translations are imported with the status you choose (e.g. Needs Review) so they can go through your normal review workflow. + +## How it works + +1. Go to **AI Translate** in the main navigation. +2. Select a **Repository**. +3. Optionally select **Target locales** (leave all unselected to translate every locale in the repository). +4. Configure options (see below). +5. Click **Start translation**. +6. The job runs in the background. You can wait for completion or leave the page. +7. If you enabled **Download JSON report**, a report per locale is available after completion. + +## Options + +| Option | Description | Default | +|--------|-------------|---------| +| **Source texts per locale** | Maximum number of source strings to translate per locale | 100 | +| **Text unit IDs** | Optional comma/whitespace-separated list of TM text unit IDs to limit the scope | — | +| **Model override** | AI model identifier (e.g. `gpt-4.1`) | gpt-4.1 | +| **Prompt suffix** | Optional text appended to the base prompt | — | +| **Related strings** | Extra context sent to the AI. See [Related strings](#related-strings) below. | NONE | +| **Translate type** | `TARGET_ONLY_NEW` = only untranslated; `TARGET_ONLY` = overwrite existing; `WITH_REVIEW` = translate all and mark for review | TARGET_ONLY_NEW | +| **Status filter** | `FOR_TRANSLATION` = only strings needing translation; `ALL` = every string | FOR_TRANSLATION | +| **Import status** | Status applied to imported translations: `REVIEW_NEEDED`, `ACCEPTED`, or `TRANSLATION_NEEDED` | REVIEW_NEEDED | +| **Request timeout (seconds)** | Per-request timeout; leave blank for server default | — | +| **Download JSON report** | Download a JSON report per locale after completion | Off | +| **Dry run** | Run without importing results (useful for testing) | Off | + +## Related strings + +**Related strings** adds extra context to each translation request so the AI can produce more natural, coherent translations. The AI is instructed to use this context (e.g. surrounding text) to match tone and improve accuracy. + +| Value | What it does | When to use | +|-------|--------------|-------------| +| **NONE** | No related strings. Each string is translated in isolation. | Default. Use when strings are independent (e.g. UI labels, buttons). | +| **USAGES** | Sends strings that appear in the *same source file* at nearby positions (by line number). Uses usage metadata from extraction (e.g. `#: file.js:2` in PO files). | Best for strings that appear in sequence (emails, documents, templates). The AI sees preceding and following text for context. | +| **ID_PREFIX** | Groups strings by the part of the name before the first dot. Sends other strings from the same group. E.g. `email.subject`, `email.body`, `email.greeting` share prefix `email`. | Best for structured keys (e.g. `screen.login.title`, `screen.login.subtitle` or `button.save`, `button.cancel`). The AI sees related strings from the same logical group. | + +**USAGES** requires that your file format provides usage/location info (e.g. PO, MacStrings). **ID_PREFIX** works with any string names that use dot-separated prefixes. + +## Dry run + +Enable **Dry run** to test your configuration without importing translations. The AI translation runs, but results are not saved. Use this to verify the model, prompt, and scope before a real run. + +## Reports + +If you enable **Download JSON report**, after the job finishes you can download a JSON report for each locale. The report contains details about the translation run for that locale. + +## Requirements + +AI Translate requires an AI translation service to be configured on the server. Contact your administrator if the feature is not available or jobs fail. diff --git a/docs/_docs/guides/authentication.md b/docs/_docs/guides/authentication.md index 75093e7995..0e959a5e30 100644 --- a/docs/_docs/guides/authentication.md +++ b/docs/_docs/guides/authentication.md @@ -11,7 +11,7 @@ permalink: /docs/guides/authentication/ authentication. This enables to have a dual authentication scheme (potentially `OAuth` for regular users and `form login` to support tools and API integrations like the `CLI`. -The integration resuse Spring Security standard settings, just prefixed with `l10n`. +The integration reuses Spring Security standard settings, just prefixed with `l10n`. #### Example with GitHub diff --git a/docs/_docs/guides/authentication_springboot3.md b/docs/_docs/guides/authentication_springboot3.md index 4c88e7808c..514be6c4f1 100644 --- a/docs/_docs/guides/authentication_springboot3.md +++ b/docs/_docs/guides/authentication_springboot3.md @@ -2,7 +2,7 @@ layout: doc title: "Authentication (Spring Boot 3 on master)" categories: guides -permalink: /docs/guides/authentication-springboot2/ +permalink: /docs/guides/authentication-springboot3/ --- {{ site.mojito_green }}'s default setup comes with a `form login` authentication backed by the database. @@ -17,7 +17,7 @@ Change or add an authentication mechanisms by updating the configuration. Eg. to l10n.security.authenticationType=DATABASE,OAUTH2 -You can chosse to either show the {{ site.mojito_green }}'s login page or to automatically redirect to another page. +You can choose to either show the {{ site.mojito_green }}'s login page or to automatically redirect to another page. Eg. to redirect to Github OAuth when the not authenticated l10n.security.unauth-redirect-to==/login/oauth2/authorization/github diff --git a/docs/_docs/guides/integrating-with-box.md b/docs/_docs/guides/integrating-with-box.md index 07a338b0dd..c176c4aa8d 100644 --- a/docs/_docs/guides/integrating-with-box.md +++ b/docs/_docs/guides/integrating-with-box.md @@ -6,6 +6,8 @@ categories: guides permalink: /docs/guides/integrating-with-box/ --- +> **Who can configure Box:** Admins only. Box integration is configured under Settings → Box Integration. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + Adding Box Platform Integration will allow project requests to be sent to the cloud. This is a great way to exchange translation files with vendors. When a translation request is made, XLIFFs will be sent to a Box folder where translation vendors can start their process. When they've completed the translations, {{ site.mojito_green }} can import the translated files from Box. @@ -46,7 +48,7 @@ For instructions on how to create the key pair: See [here](https://docs.box.com/ > >If Oracle JDK is used to run {{ site.mojito_green }}, this will require **JCE** to be installed (for JDK7 see [here](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html)). -Otherwise, an exception like the folllowing will be thrown: +Otherwise, an exception like the following will be thrown: > >`Caused by: java.security.InvalidKeyException: Illegal key size`. > diff --git a/docs/_docs/guides/manage-users.md b/docs/_docs/guides/manage-users.md index 2d960fe1a3..9eaaef6767 100644 --- a/docs/_docs/guides/manage-users.md +++ b/docs/_docs/guides/manage-users.md @@ -5,17 +5,19 @@ categories: guides permalink: /docs/guides/manage-users/ --- +> **Who can manage users:** **Project Managers** and **Admins** can access User Management (Settings → User Management). Translators and Users cannot. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + The default authentication used by {{ site.mojito_green }} relies on the database l10n.security.authenticationType=DATABASE User information is stored in database and all the authentication process -is handle by the server. Managing users is done +is handled by the server. Managing users is done via the CLI. -Alternatively, [LDAP]({{ site.url }}/docs/guides/ldap-authentication) can be used. +Alternatively, [LDAP]({{ site.url }}/docs/guides/authentication/#ldap) can be used. -### Bootstraping +### Bootstrapping {{ site.mojito_green }} initially is set up with one default user `admin/ChangeMe`. You can override the default user settings. These values are only respected on initial bootstrapping. @@ -31,12 +33,12 @@ You can override the default user settings. These values are only respected on i --given-name ${GIVEN_NAME} --common-name ${COMMON_NAME} -Enter password when promted. +Enter password when prompted. ### Update password mojito user-update --username ${USERNAME} --password -Enter password when promted. +Enter password when prompted. ### Delete user mojito user-delete --username ${USERNAME} \ No newline at end of file diff --git a/docs/_docs/guides/springboot3_migration.md b/docs/_docs/guides/springboot3_migration.md index 6b277cc89d..b3e86a2efe 100644 --- a/docs/_docs/guides/springboot3_migration.md +++ b/docs/_docs/guides/springboot3_migration.md @@ -2,7 +2,7 @@ layout: doc title: "Spring Boot 3 migration" categories: guides -permalink: /docs/guides/authentication-springboot3/ +permalink: /docs/guides/springboot3-migration/ --- Changes from Spring 2.x to Spring 3.x diff --git a/docs/_docs/refs/configurations.md b/docs/_docs/refs/configurations.md index 0705299821..7cfc54a9a9 100644 --- a/docs/_docs/refs/configurations.md +++ b/docs/_docs/refs/configurations.md @@ -18,9 +18,11 @@ To override default configurations of {{ site.mojito_green }}, add them in /usr/local/etc/mojito/cli/application.properties # for mojito cli /usr/local/etc/mojito/webapp/application.properties # for mojito webapp -If you want to use different path to store the override configuration, you can specify the following extra parameter when you start {{ site.mojito_green }} server and when you run {{ site.mojito_green }} CLI. For example, +If you want to use a different path for override configuration, specify the following when you start the server or run the CLI: - -Dspring.config.location=file:/${YOUR_PATH}/application.properties + -Dspring.config.additional-location=optional:file:/${YOUR_PATH}/application.properties + +Using `additional-location` adds your file to the default configuration. Use `optional:` so startup succeeds even if the file is missing. ## Database Configuration @@ -37,8 +39,8 @@ The default database configuration of {{ site.mojito_green }} is in-memory HSQL You can override the database configuration with MySQL. -[Install MySQL 5.7](http://dev.mysql.com/doc/refman/5.7/en/installing.html) and then create a database for {{ site.mojito_green }} -(with Brew: `brew install mysql@5.7`). +[Install MySQL 8](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/) and then create a database for {{ site.mojito_green }} +(with Brew: `brew install mysql@8`). Connect to MySQL DB as root user @@ -61,10 +63,10 @@ Configure {{ site.mojito_green }} to use MySQL. When using MySQL, Flyway must be spring.jpa.database=MYSQL spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect spring.jpa.hibernate.ddl-auto=none - spring.datasource.url=jdbc:mysql://localhost:3306/${DB_NAME}?characterEncoding=UTF-8&useUnicode=true + spring.datasource.url=jdbc:mysql://localhost:3306/${DB_NAME}?characterEncoding=UTF-8&useUnicode=true&useSSL=false&serverTimezone=UTC spring.datasource.username=${DB_USERNAME} spring.datasource.password=${DB_PASSWORD} - spring.datasource.driverClassName=com.mysql.jdbc.Driver + spring.datasource.driverClassName=com.mysql.cj.jdbc.Driver spring.datasource.testOnBorrow=true spring.datasource.validationQuery=SELECT 1 @@ -75,8 +77,8 @@ Configure {{ site.mojito_green }} to use MySQL. When using MySQL, Flyway must be l10n.org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreTX l10n.org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate l10n.org.quartz.jobStore.dataSource=myDS - l10n.org.quartz.dataSource.myDS.driver=com.mysql.jdbc.Driver - l10n.org.quartz.dataSource.myDS.URL=jdbc:mysql://localhost:3306/${DB_NAME}?characterEncoding=UTF-8&useUnicode=true + l10n.org.quartz.dataSource.myDS.driver=com.mysql.cj.jdbc.Driver + l10n.org.quartz.dataSource.myDS.URL=jdbc:mysql://localhost:3306/${DB_NAME}?characterEncoding=UTF-8&useUnicode=true&useSSL=false&serverTimezone=UTC l10n.org.quartz.dataSource.myDS.user=${DB_USERNAME} l10n.org.quartz.dataSource.myDS.password=${DB_PASSWORD} l10n.org.quartz.dataSource.myDS.maxConnections=12 @@ -136,6 +138,24 @@ When translators are done, translated xliff files should be put in the `Localize You can override this default configuration and have project requests to be managed on Box instead of local file system. Refer to [Integrating with Box]({{ site.url }}/docs/guides/integrating-with-box/). +### AI Translation Configuration + +AI Translate uses the OpenAI API to batch-translate repositories. To enable it, set the OpenAI API key: + + l10n.ai-translate.openai-client-token=${OPENAI_API_KEY} + +Optional settings: + + l10n.ai-translate.model-name=gpt-4o-2024-08-06 + l10n.ai-translate.scheduler-name=default + +- `openai-client-token`: Required. Your OpenAI API key. Without it, the AI Translate page is disabled. +- `model-name`: Default model for translation (default: `gpt-4o-2024-08-06`). Can be overridden per run in the UI. +- `scheduler-name`: Quartz scheduler for AI translation jobs. Use a dedicated scheduler name when running multiple Quartz schedulers (e.g. `l10n.ai-translate.scheduler-name=ai-translate`). + +For AI Review (translation quality review), use the `l10n.ai-review.*` prefix with the same properties: `openai-client-token`, `model-name`, `scheduler-name`. + + ### Database Authentication The default user authentication setting in {{ site.mojito_green }} is to use database. User information is stored in database. {{ site.mojito_green }} initially is set up with one default user `admin/ChangeMe`. You can override the default user settings. These values are only respected on initial bootstrapping. @@ -146,10 +166,10 @@ The default user authentication setting in {{ site.mojito_green }} is to use dat With database authentication, {{ site.mojito_green }} users can be added, updated (with new password) and deleted using {{ site.mojito_green }} CLI. - # add user - enter password when promted + # add user - enter password when prompted mojito user-create --username ${USERNAME} --password --surname ${SURNAME} --given-name ${GIVEN_NAME} --common-name ${COMMON_NAME} - # update password - enter password when promted + # update password - enter password when prompted mojito user-update --username ${USERNAME} --password # delete user @@ -271,7 +291,7 @@ You can also optionally use it in production by setting the following configurat The ID of the newly created `mojito` folder will be stored and used as the rootFolderId - + |-> mojito |-> Project Requests diff --git a/docs/_docs/refs/configurations_springboot2.md b/docs/_docs/refs/configurations_springboot2.md index a823f5c7a7..1b958b55c8 100644 --- a/docs/_docs/refs/configurations_springboot2.md +++ b/docs/_docs/refs/configurations_springboot2.md @@ -27,7 +27,7 @@ If you want to use different path to store the override configuration, you can s The default database configuration of {{ site.mojito_green }} is in-memory HSQL database. - spring.flyway.eanbled=false + spring.flyway.enabled=false spring.datasource.url=jdbc:hsqldb:mem:testdb;DB_CLOSE_DELAY=-1 spring.datasource.initialization-mode=embedded spring.datasource.data=classpath:/db/hsql/data.sql @@ -96,7 +96,7 @@ Depending on the file size that will be processed, it might be required to incre If using a older version of MySQL, there is a [known issue](https://github.com/box/mojito/issues/120) when creating the schema. One workaround is to use `utf8` instead `utf8mb4` but it has its limitation in term of character support. -We recommand to run both MySQL and the Java service using `UTC` timezone (or a least make sure they both the same timezone). To set +We recommend running both MySQL and the Java service using `UTC` timezone (or a least make sure they both the same timezone). To set `UTC` as default use the following: ```properties @@ -149,10 +149,10 @@ The default user authentication setting in {{ site.mojito_green }} is to use dat With database authentication, {{ site.mojito_green }} users can be added, updated (with new password) and deleted using {{ site.mojito_green }} CLI. - # add user - enter password when promted + # add user - enter password when prompted mojito user-create --username ${USERNAME} --password --surname ${SURNAME} --given-name ${GIVEN_NAME} --common-name ${COMMON_NAME} - # update password - enter password when promted + # update password - enter password when prompted mojito user-update --username ${USERNAME} --password # delete user @@ -229,7 +229,7 @@ You can also optionally use it in production by setting the following configurat The ID of the newly created `mojito` folder will be stored and used as the rootFolderId - + |-> mojito |-> Project Requests diff --git a/docs/_docs/refs/mojito-file-formats.md b/docs/_docs/refs/mojito-file-formats.md index 74f85e7a33..c5465dd63b 100644 --- a/docs/_docs/refs/mojito-file-formats.md +++ b/docs/_docs/refs/mojito-file-formats.md @@ -72,7 +72,6 @@ Localized Resource File (Spanish): `es.lproj/Localizable.strings` | 2 | Source | | 3 | Target | | 4 | Comment | -||| Source Resource File (English): `example.csv` diff --git a/docs/_docs/refs/mojito-locales.md b/docs/_docs/refs/mojito-locales.md index db7d0d2465..e21cdc6b83 100644 --- a/docs/_docs/refs/mojito-locales.md +++ b/docs/_docs/refs/mojito-locales.md @@ -56,7 +56,7 @@ permalink: /docs/refs/mojito-locales/ | en-US | English (United States) | | en-ZA | English (South Africa) | | en-ZW | English (Zimbabwe) | -| en-419 | Spanish (Latin America) | +| es-419 | Spanish (Latin America) | | es-AR | Spanish (Argentina) | | es-BO | Spanish (Bolivia) | | es-CL | Spanish (Chile) | diff --git a/docs/_docs/refs/monitoring.md b/docs/_docs/refs/monitoring.md new file mode 100644 index 0000000000..061be4e19c --- /dev/null +++ b/docs/_docs/refs/monitoring.md @@ -0,0 +1,39 @@ +--- +layout: doc +title: "Database Monitoring" +date: 2025-02-04 10:00:00 -0800 +categories: refs +permalink: /docs/refs/monitoring/ +--- + +The Database Latency page lets you measure database response times to diagnose performance issues. + +> **Who can use Monitoring:** Admins only. The **Monitoring** link appears in your user menu (top right, under your username) only if you have the Admin role. Translators and Project Managers do not see this option. See [User Roles & Permissions]({{ site.url }}/docs/guides/user-roles-overview/). + +## How to access + +1. Click your username in the top-right corner. +2. Click **Monitoring** in the dropdown. +3. The Database Latency page opens at `/monitoring`. + +## What it measures + +The page runs database probes and reports latency (response time in milliseconds): + +| Probe | Description | +|-------|-------------| +| **Direct JDBC (select 1)** | Raw JDBC connection executing a simple query | +| **Hibernate (select 1)** | Hibernate health check | +| **Hibernate repositories query** | A typical repositories query as used by the application | + +For each probe, you get: +- **Min**, **Max**, **Average** latency (ms) +- Per-iteration measurements + +## How to use it + +1. Set **Iterations** (1–20, default 5). More iterations give a more stable average. +2. Click **Measure**. +3. Review the results. High or variable latency may indicate database or network issues. + +Use this when troubleshooting slow page loads or when tuning database configuration. diff --git a/docs/_docs/refs/springboot2migration.md b/docs/_docs/refs/springboot2migration.md index b3994ae4aa..303d0c07f2 100644 --- a/docs/_docs/refs/springboot2migration.md +++ b/docs/_docs/refs/springboot2migration.md @@ -32,8 +32,8 @@ Optional: Everything that `Spring boot 2.x` brings can potentially be re-used in Mojito. A few things to call-out though: -* Improved OAuth2 support: multiple registrations, improved login page (see [details](/docs/guides/authentication/#oauth-2)) -* Monitoring with `micrometer` (statds dependency was added) +* Improved OAuth2 support: multiple registrations, improved login page (see [details]({{ site.url }}/docs/guides/authentication/#oauth-2)) +* Monitoring with `micrometer` (statsd dependency was added) ## Known issue diff --git a/docs/documentation.md b/docs/documentation.md index 4355bb93c7..9e456e7a07 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -4,6 +4,8 @@ title: Documentation permalink: /docs/ --- +

Using the webapp? Start with User Roles & Permissions to see what you can do based on your role (Translator, Project Manager, Admin, or User).

+

Guides

{% assign docs=site.docs | sort: 'path' %} {% for my_page in docs %}