feat: Visual editor and formats support docs & blog post

blog/2024-03-05-releasing-visual-editor-and-formats-support.mdx

@@ -0,0 +1,130 @@
+---
+slug: releasing-visual-editor-and-formats-support
+title: 'Visual Editor and support for iOS, Android, Flutter, .po and more'
+description: 'Our latest release includes a visual editor and extends support for various formats including iOS, Android, Flutter, .po and more'
+authors: [jcizmar]
+tags: ['tolgee', 'android', 'apple', 'ios', 'flutter', 'php', 'po', 'c++']
+image: '/img/blog/visual-editor-and-formats-support/og_image_light.webp'
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+<ThemedImage
+  alt="Visual editor and formats support"
+  sources={{
+    light: useBaseUrl(
+      '/img/blog/visual-editor-and-formats-support/og_image_light.webp'
+    ),
+    dark: useBaseUrl(
+      '/img/blog/visual-editor-and-formats-support/og_image_dark.webp'
+    ),
+  }}
+/>
+
+We are happy to announce that we finally released tools enabling you to use Tolgee to translate also to **iOS, Mac and other Apple platform Apps, Android, Flutter,
+PHP and C++**. Also, you can reliably export to generic formats like **Structured JSON** with support for arrays or **XLIFF**.
+
+To provide a convenient way of editing translations for developers, translators, localization managers, project managers and other stakeholders, **we
+made our translation editor visual**, so you can conveniently edit plurals and you can edit strings without the need to understand the
+placeholders or HTML tags syntax.
+
+<!--truncate-->
+
+## New Formats Support
+
+Tolgee now supports the following formats:
+
+- Tolgee Native JSON
+- Generic Structured JSON (With Arrays Support)
+- Generic XLIFF
+- Apple .strings and .stringsdict (for iOS, macOS and other Apple platforms)
+- Android Resources XML
+- Flutter ARB
+- PHP Gettext .po
+- C/C++ Gettext .po
+- Java (.properties)
+
+Convenient plurals editing in the visual editor is supported for all formats as well as placeholders visualization as
+described below.
+
+## The Visual Editor
+
+There are several issues regarding editing translation messages in different message formats and raw HTML. For
+example this ICU message:
+
+```
+Hello, {name}! You have been promoted to <strong>{position}</strong>
+```
+
+To edit this message, the translator needs to understand the **ICU Message Syntax**, so they know the `{name}` and
+`{position}` are placeholders representing the user's name and new position. They need to understand that the `<strong>` is
+an HTML tag they must not translate (e.g., to `<fuerte>` to Spanish). The purpose of a visual editor is to hide the syntax
+from the translators and provide a convenient way to edit such messages.
+
+import { ScreenshotWrapper } from '../platform/shared/_ScreenshotWrapper';
+
+<ScreenshotWrapper
+  src="/img/blog/visual-editor-and-formats-support/visual_editor.webp"
+  alt="Visual editor"
+/>
+
+This way, the translator to Spanish only needs to type the actual translated text and add the placeholders by
+clicking the missing placeholders below the input field.
+
+Another benefit of the visual editor is the convenience when editing **right-to-left** language translations.
+The placeholders and HTML are still left-to-right; mixing them with right-to-left leads to weird cursor movements and
+behavior. When displaying visualized placeholders instead of the raw syntax, the translator's cursors always move
+naturally, and they don't have to think about the order of opening and closing HTML tags.
+
+## Tolgee Universal ICU Placeholders
+
+For formats that are not natively using ICU Message Format, Tolgee can convert the placeholders to
+the **Tolgee Universal ICU Placeholders** when importing, so you can edit them in the visual editor.
+These placeholders are then converted back when exporting.
+[Read more about this concept in docs](/platform/translation_process/tolgee_universal_icu_placeholders).
+
+The main benefit of using unified placeholder syntax is that you're able to use the same localization data in different
+target platforms since these placeholders can be converted to every supported format.
+
+## Convenient Plural Editing
+
+The ICU Message format was always native for Tolgee since it greatly supports plurals and has formatted
+implementations in many programming languages. However, editing such plural messages can be challenging for translators.
+
+E.g., the following ICU message:
+
+```
+{count, plural, one {You have one message} other {You have {count} messages}}
+```
+
+Using the visual editor, you can easily edit each form separately, which makes the translation much more convenient,
+while hiding the relatively complex ICU syntax from translators.
+
+<ScreenshotWrapper
+  src="/img/blog/visual-editor-and-formats-support/editing_plural_tools.webp"
+  alt="Editing plural"
+/>
+
+Also, all the tools like Translation memory or Machine translation show only the single plural form translation.
+
+## Shiny New Layout
+
+To make the Tolgee Translations view more flexible, **we moved the translation tools, the comments and history to the right panel**. The right panel provides a single interface for all the views and allows us to add
+new panels in the future. We also plan to introduce the ability to create custom apps and expose access to this panel in
+the API to give developers a way to create custom tools for their needs.
+
+<ScreenshotWrapper
+  src="/img/blog/visual-editor-and-formats-support/new_layout.webp"
+  alt="New layout"
+/>
+
+## TL;DR
+
+- Our latest release streamlines Tolgee's use across various platforms, including iOS, Mac, Android, Flutter, PHP, and C++.
+- It enables a wider range of formats, a visual editing experience, and a fresh layout for more seamless translation and localization processes.
+- Enhanced placeholder and plural editing simplifies the translation effort, encouraging consistency across formats.
+
+Let us know in the [Tolgee Slack community](https://Tolg.ee/slack) if you have any questions about those new features!
+
+[![Demo banner](/img/blog/blog-banners/banner-demo.webp)](https://calendly.com/tolgee/30min)

docusaurus.config.js

@@ -28,6 +28,16 @@ const config = {
     prism: {
       additionalLanguages: ['icu-message-format'],
     },
+    zoom: {
+      selector: '.zoomable-image',
+      background: {
+        light: 'rgb(255, 255, 255)',
+        dark: '#182230',
+      },
+      config: {
+        // options you can specify via https://github.com/francoischalifour/medium-zoom#usage
+      },
+    },
   },
   presets: [
     [
@@ -72,6 +82,7 @@ const config = {
   ],
   plugins: [
     'docusaurus2-dotenv',
+    'docusaurus-plugin-image-zoom',
     ['@docusaurus/plugin-client-redirects', redirects],
     async function tailwind() {
       return {

package.json

@@ -35,6 +35,7 @@
     "@types/styled-components": "5.1.14",
     "autoprefixer": "10.4.7",
     "clsx": "^1.1.1",
+    "docusaurus-plugin-image-zoom": "1.0.1",
     "docusaurus-tailwindcss": "^0.1.0",
     "docusaurus2-dotenv": "^1.4.0",
     "eslint": "^7.32.0",

platform/account_settings/api_keys_and_pat_tokens.mdx

@@ -5,6 +5,8 @@ sidebar_label: API keys and PAT tokens
 description: 'Learn more about API keys and PAT tokens (=authentication methods enabling you to manage your data via REST API.)'
 ---
 
+import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
+
 API keys and PAT tokens are authentication methods enabling you to manage your data via REST API.
 
 ## Project API keys
@@ -33,7 +35,10 @@ Project API keys can be generated by accessing user menu (Avatar in Top right) >
 
 Then you can generate a project API by filling in required fields and selecting scopes.
 
-![API key generation](/img/docs/platform/project_api_key_generation.png)
+<ScreenshotWrapper
+  src="/img/docs/platform/project-api-key.webp"
+  alt="API key generation"
+/>
 
 ### Regeneration
 
@@ -73,7 +78,7 @@ To access your API keys, open user menu (Avatar in Top right) and select `Person
 
 Project API keys can be generated by accessing user menu (Avatar in Top right) > `Personal Access Tokens` > `+ Add` button.
 
-![API key generation](/img/docs/platform/project_pat_generation.png)
+<ScreenshotWrapper src="/img/docs/platform/pat.webp" alt="PAT key generation" />
 
 ### Regeneration
 

platform/account_settings/password_and_2fa.mdx

@@ -4,18 +4,25 @@ title: Password and 2FA
 sidebar_label: Password and 2FA
 ---
 
+import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
+
 ## Account security
+
 The Account security page allows you to change your password and enable two-factor authentication (2FA).
 You can access this page by clicking your username in the top right corner of the page and selecting `Account settings` from the dropdown menu and then clicking `Account security` in the left sidebar.
 
-![Account security page](/img/docs/platform/account_security_page.png)
+<ScreenshotWrapper
+  src="/img/docs/platform/account-security.webp"
+  alt="Account security page"
+/>
 
 ### Two-Factor Authentication
+
 Two-Factor Authentication (2FA) is a security feature that requires you to enter a code in addition to your password when you log in.
 This code is generated by an app on your phone. **We recommend enabling 2FA** to protect your account.
 
 To enable 2FA, click the `Enable 2FA` button. You will be prompted to enter your password and a code generated by an app on your phone.
 
-![Enable 2FA](/img/docs/platform/enable_2fa.png)
+<ScreenshotWrapper src="/img/docs/platform/two-factor.webp" alt="Enable 2FA" />
 
-After you confirm to enable 2FA, recovery codes will be generated. **Write down these codes and keep them in a safe place**. You will need them if you lose access to your phone.
+After you confirm to enable 2FA, recovery codes will be generated. **Write down these codes and keep them in a safe place**. You will need them if you lose access to your phone.