Forem: Jan Cizmar

I have localized the best short-linking platform in the world

Jan Cizmar — Wed, 06 Nov 2024 10:18:05 +0000

As part of playing with Tolgee, I have tried translating dub.co, a well-established open-source company, into other languages! It took me 1 hour, and the results are astonishing!

In this tutorial, I’ll walk you through an easy and efficient approach to localization in a Next.js application using Tolgee - a platform designed for fast and autonomous translation management.

You will also learn how to integrate Tolgee with Dub.co, a popular link management platform allowing users to access and interact with the application in their preferred languages.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

You will also need to set up the following:

Tolgee Project - an existing project with at least two language translations.
Tolgee CLI - allows you to interact with the Tolgee platform from your computer using the command line.
Docker - required for running Dub.co. It is an open-source platform that uses containerization to make it easier to create, deploy, and run applications.
Docker Compose - a software application for defining and running multi-container Docker applications.
Python (version 3.8 or higher): necessary for configuring some of Dub.co’s packages.

What is Tolgee?

Tolgee is a developer-friendly localization platform that allows you to translate your application into any language without modifying your code. It is designed for web applications but also supports mobile and desktop applications.

With Tolgee, you don't need to look for keys in your source code, edit localization files, or perform manual exporting data for translators. Tolgee offers in-context translation, a translation memory for keeping track of already translated strings, machine and auto translations, and many others.

Please help us with a star. 🥹

It would help us to create more articles like this 💖

Star the Tolgee repository ⭐

How to set up Dub.co on your local computer

Dub.co is an open-source link management platform that allows marketing teams to add powerful analytics to their links, create short links, generate QR codes for links, and many more. It was created by Steven Tey (formerly of Vercel).

Follow these steps to set up Dub.co on your computer:

Clone the Dub.co GitHub repository by running the code snippet below.

git clone https://github.com/dubinc/dub.git

Navigate into the dub folder and install the project dependencies:

pnpm install

Within the apps/web folder, rename the .env.example file to .env.

Create a new Tinybird account, and copy your Admin Auth Token into the .env file.

TINYBIRD_API_KEY=<your_admin_auth_token>

Navigate into the packages/tinybird directory and install the Tinybird CLI using the following command:

pip3 install tinybird-cli

Execute the following command in your terminal and enter your Admin Auth Token when prompted to authenticate using the Tinybird CLI:

tb auth

Publish the Tinybird datasource and endpoints by running the code snippet below:

tb push

Create an Upstash database and copy the following credentials from the REST API section to the .env file:

UPSTASH_REDIS_REST_URL=<your_rest_url>
UPSTASH_REDIS_REST_TOKEN=<your_rest_token>

Navigate to the QStash tab and copy the following credentials into the .env file.

QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=

Next, within the apps/web directory, run the following command to start the Docker Compose stack:

docker-compose up

Generate the Prisma client and create its database tables using the following commands:

npx prisma generate
npx prisma db push

Dub.co supports multiple authentication methods. Create a GitHub app and copy the URL below as its callback URL.

http://localhost:8888/api/auth/callback/github

Finally, start the development server:

pnpm dev

You can access the web application by navigating to http://localhost:8888 in your browser, create a workspace, and get started. If you encounter any issues, refer to the complete installation guide for more detailed assistance.

How to configure Tolgee in a Next.js application

In this section, you'll learn how to add Tolgee to a Next.js application and configure it to support multiple languages, allowing users to access the app in their preferred language.

To implement localization in Next.js applications, you will need to install the Tolgee React SDK.

npm install @tolgee/react

Next, create a Tolgee Platform account and sign into your dashboard.

Add a new project by clicking the Project button and selecting your preferred languages for the project. For this application, we'll use five languages: English (as the base language), Chinese, Hindi, Spanish, and Arabic.

Click the profile icon in the top-right corner of your dashboard, then select Project API Keys to create an API key for your Tolgee project.

Create a .env.development.local and copy your API key into the file:

NEXT_PUBLIC_TOLGEE_API_KEY=<paste_your_API_key_here>
NEXT_PUBLIC_TOLGEE_API_URL=https://app.tolgee.io

Select Translations from the sidebar menu and add a new translation to the project.

You can create a translation key, add the content or string you need to translate, provide a description, and then save it.

Tolgee provides various machine translation options by default, allowing you to easily translate content into the available languages within your project.

Congratulations! You’ve successfully set up the Tolgee platform for translations within your application. Next, let’s configure Tolgee within the Dub.co project to easily generate translations directly in the application.

How to set up localization in Dub.co

In this section, I’ll guide you through configuring Tolgee to support client-server interactions within the Dub.co project.

First, install the Tolgee CLI package.

npm install --global @tolgee/cli

Run the following code snippet to sign into your Tolgee platform using your project API key.

tolgee login <your_tolgee_api_key>

Next, create an i18n folder within the apps/web directory. This folder will store the JSON files containing translations for the various languages available in the Tolgee platform project.

apps
├── web #👈🏼 this folder
    ├── app 
    ├── i18n  #👈🏼 newly created 
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Within the apps/web directory, fetch the language translations created in your Tolgee project by running the code snippet below:

tolgee --project-id <tolgee_platform_project_id> pull --path ./i18n

The code snippet above automatically populates the i18n folder with the various language translations created within the Tolgee platform.

apps
├── web 
    ├── app 
    ├── i18n #👇🏻 translation files
        ├── ar.json
        ├── en.json
        ├── es.json 
        ├── zh.json  
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Create a tolgee folder which will contain Tolgee configurations within the apps/web directory:

apps
├── web # 👈🏼 this folder
    ├── app 
    ├── i18n  
    ├── tolgee # 👈🏼 Tolgee folder
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Add a shared.ts file in the tolgee directory, then copy the following code snippet into the file:

import { FormatIcu } from "@tolgee/format-icu";
import { DevTools, Tolgee } from "@tolgee/react";

const apiKey = process.env.NEXT_PUBLIC_TOLGEE_API_KEY;
const apiUrl = process.env.NEXT_PUBLIC_TOLGEE_API_URL;

//👇🏻 available translations
export const ALL_LOCALES = ["en", "ar", "es", "zh"];

//👇🏻 default translation
export const DEFAULT_LOCALE = "en";

//👇🏻 returns an object containing the translation files
export async function getStaticData(languages: string[]) {
  const result: Record<string, any> = {};

  for (const lang of languages) {
    result[lang] = (await import(`../i18n/${lang}.json`)).default;
  }

  return result;
}

export function TolgeeBase() {
  return Tolgee().use(FormatIcu()).use(DevTools()).updateDefaults({
    apiKey,
    apiUrl,
    fallbackLanguage: "en",
    defaultLanguage: DEFAULT_LOCALE,
  });
}

The code snippet above configures Tolgee with default and fallback languages to enable localization within the application.

Next, create a client.tsx file in the tolgee directory, then copy the code snippet below into the file:

'use client';

import { TolgeeBase } from './shared';
import { TolgeeProvider, useTolgeeSSR } from '@tolgee/react';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

type Props = {
  locales: any;
  locale: string;
  children: React.ReactNode;
};

const tolgee = TolgeeBase().init();

export const TolgeeNextProvider = ({ locale, locales, children }: Props) => {
  const tolgeeSSR = useTolgeeSSR(tolgee, locale, locales);
  const router = useRouter();

  useEffect(() => {
    const { unsubscribe } = tolgeeSSR.on('permanentChange', () => {
      router.refresh();
    });

    return () => unsubscribe();
  }, [tolgeeSSR, router]);

  return (
    <TolgeeProvider
      tolgee={tolgeeSSR}
      options={{ useSuspense: false }}
      fallback="Loading"
    >
      {children}
    </TolgeeProvider>
  );
};

The client.tsx file serves the purpose of translating client components and also enables the in-context functionality for server-rendered components. The code snippet above defines the TolgeeNextProvider component, which wraps the entire Dub.co application, providing configurations needed to manage language changes and translations.

Create a custom locale.ts file in the tolgee folder and copy the following code snippet into it:

"use server";

import { cookies, headers } from "next/headers";
import { ALL_LOCALES, DEFAULT_LOCALE } from "./shared.ts";

const COOKIE_NAME = "NEXT_LOCALE";

//👇🏻 Retrieves the current language setting for the user.
// If not set, it attempts to detect the user's language from browser preferences.
// Defaults to the application's default locale if no match is found.
export async function getUserLocale() {
  return (
    cookies().get(COOKIE_NAME)?.value || detectLanguage() || DEFAULT_LOCALE
  );
}

//👇🏻 Sets the user’s preferred language in a cookie to persist their selection.
export async function setUserLocale(locale: string) {
  cookies().set(COOKIE_NAME, locale);
}

//👇🏻 Attempts to detect the user's preferred language based on browser settings.
const detectLanguage = () => {
  const allPreferred = getAcceptedLanguages();

  for (const language of allPreferred) {
    // Checks for an exact match in the list of supported locales
    const exactMatch = ALL_LOCALES.find((l) => l === language);
    if (exactMatch) {
      return exactMatch;
    }

    // Falls back to matching only the two-letter language code
    const getTwoLetters = (fullTag: string) =>
      fullTag.replace(/^(.+?)(-.*)?$/, "$1");

    const preferredTwoLetter = getTwoLetters(language);
    const twoLetterMatch = ALL_LOCALES.find(
      (l) => getTwoLetters(l) === preferredTwoLetter,
    );
    if (twoLetterMatch) {
      return twoLetterMatch;
    }
  }
};

//👇🏻 Retrieves accepted languages from the "Accept-Language" HTTP header.
// Returns an array of languages in order of preference.
function getAcceptedLanguages() {
  const acceptLanguageHeader = getAcceptLanguageHeader();
  if (!acceptLanguageHeader) {
    return [];
  }

  // Splits the header value by commas to separate each language code
  return acceptLanguageHeader.split(",").map((lang) => {
    const [language] = lang.split(";");
    return language.trim();
  });
}

//👇🏻 Fetches the "Accept-Language" HTTP header from the user's browser.
// This header lists languages preferred by the user, ranked by preference.
function getAcceptLanguageHeader() {
  return headers().get("Accept-Language");
}

Finally, create a server.tsx file in the tolgee folder, then copy the following code snippet into the file:

import { getUserLocale } from "./locale.ts";
import { TolgeeBase, ALL_LOCALES, getStaticData } from './shared';
import { createServerInstance } from '@tolgee/react/server';

export const { getTolgee, getTranslate, T } = createServerInstance({
   getLocale: async () => getUserLocale(),
  createTolgee: async (locale) =>
    TolgeeBase().init({
      // including all locales
      // on server we are not concerned about bundle size
      staticData: await getStaticData(ALL_LOCALES),
      observerOptions: {
        fullKeyEncode: true,
      },
      language: locale,
      fetch: async (input, init) => {
        const data = await fetch(input, { ...init, next: { revalidate: 0 } });
        return data;
      },
    }),
});

The application utilizes the React server cache for sharing Tolgee instance across components in a single render. This allows the app to use the Tolgee instance anywhere in the server components.

Congratulations! You’ve successfully configured Tolgee and are now ready to start adding translations to various content within the application.

How to translate your application content with Tolgee

Here, you'll learn how to translate content within your web application and see how Tolgee enables easy in-app translation.

To get started, you need to wrap the entire Dub.co application with the TolgeeNextProvider component, defined in tolgee/client.tsx. Navigate to the apps/web/app folder, then go to the app.dub.co/(dashboard) directory, and update the layout.tsx file as shown below:

import { MainNav } from "@/ui/layout/main-nav";
import { HelpButtonRSC } from "@/ui/layout/sidebar/help-button-rsc";
import Toolbar from "@/ui/layout/toolbar/toolbar";
import { constructMetadata } from "@dub/utils";
import { ReactNode } from "react";
import Providers from "../../providers";
//👇🏻 Tolgee imports
import { TolgeeNextProvider } from "../../../tolgee/client.tsx";
import { getUserLocale } from "../../../tolgee/locale.ts";
import { getStaticData } from "../../../tolgee/shared.ts";


export const metadata = constructMetadata();

export default async function Layout({ children }: { children: ReactNode }) {
  const locale = await getUserLocale();
  const locales = await getStaticData([locale, "en"]);

  return (
    <TolgeeNextProvider locale={locale} locales={locales}>
      <Providers>
        <div className="min-h-screen w-full bg-white">
          <MainNav toolContent={<HelpButtonRSC />}>{children}</MainNav>
        </div>
        {/* <ChangelogPopup /> */}
        <Toolbar show={["onboarding"]} />
      </Providers>
    </TolgeeNextProvider>
  );
}

The code snippet above wraps the dashboard routes with the Tolgee provider, enabling language switching and localization throughout the application.

Tolgee provides two hooks to help you select and translate text within your application: useTolgee and useTranslate.

The useTolgee hook returns the Tolgee instance, allowing you to subscribe to various events that will trigger re-renders when translating text.
The useTranslate hook includes a translation function (t function) that renders the actual translations directly within the app.

Update the page.tsx file in the app.dub.co/(dashboard)/[slug] directory by adding the following code snippet:

"use client";
import { PageContent } from "@/ui/layout/page-content";
import WorkspaceLinksClient from "./page-client";
//👇🏻 Tolgee installations
import { useTolgee, useTranslate } from "@tolgee/react";
import { setUserLocale } from "tolgee/locale";


export default function WorkspaceLinks() {
  const { t } = useTranslate();
  const tolgee = useTolgee(["pendingLanguage"]);
  const language = tolgee.getPendingLanguage();

  return (
    <PageContent title="Links">
    {/** -- HTML input for selecting the preferred language -- */}
      <div className="flex w-full flex-col px-10">
        <p>Select Language</p>
        <select
          defaultValue={language}
          className="rounded-sm"
          name="locale"
          id="locale"
          onChange={(e) => setUserLocale(e.currentTarget.value)}
        >
          <option value="en">English</option>
          <option value="es">Spanish</option>
          <option value="ar">Arabic</option>
          <option value="zh">Chinese</option>
        </select>

        <p>{t("hello")}</p>
      </div>
    {/** -- end of Tolgee -- */}
      <WorkspaceLinksClient />
    </PageContent>
  );
}

The code snippet above displays an HTML <select> tag that allows users to choose and switch between different languages. The {t("hello")} element uses Tolgee’s translation function to render a value of the "hello" key based on the selected language.

Finally, you can update the remaining content throughout the application to support language changes, allowing users to view all components in their selected language.

Tolgee also provides an in-context translation feature, allowing you to translate strings directly within your application, whether in development or production, simply by clicking the text and holding the Alt or Option key.

Congratulations! You've successfully completed the project for this tutorial.

The source code for this tutorial is available here:

https://github.com/JanCizmar/dub-with-tolgee

Conclusion

So far, you’ve learnt how to add localization to your software applications using Tolgee, implement support for multiple languages, and make language switching seamless within a real-world project.

Tolgee is a fast, developer-focused localization platform that allows you to provide context to your content and generate translations in seconds. It also supports multiple JavaScript frameworks, including Vue, Angular, and Svelte, and integrates with tools like Figma and a REST API for flexibility.

If you're looking to create a personalized experience for your users, Tolgee is an excellent choice. Feel free to contribute and star our GitHub repository, and join our Slack community to connect with others and engage with the team.

Thank you for reading!

I easily translated my React.js applications into multiple languages. Here is how... 🤯

Jan Cizmar — Mon, 23 Sep 2024 13:35:30 +0000

Translating an App to multiple languages (localization) is tricky part of many applications.

Tolgee is simplifying the localization process and saves developer's time by removing repetitive tasks 🔁 ❌

Saving time? That's what I want. Show me how to localize my React app!

What is Tolgee

Tolgee is an open-source i18n tool combining localization platform and SDKs to provide simple way to translate the web applications for both developers and translators.

Tolgee is not just another software localization platform offering integrations that only syncs local data with the backend. Instead, Tolgee is truly integrated into your app via SDKs.

In context translating 📖

As a developer of localized application, you probably have to modify localization data every time you need to change a text.

So you have to open the file, add or find the key to modify, save it and check whether everything was changed correctly in the app.

With Tolgee you can just ALT + click the actual translated text in your app and 💥boom💥 translation dialog appears and you are able to translate it right away.

Automatic Screenshot Generation 📸

Another tricky part of localization is providing context to translators. Only exporting the keys and translations in source language is not always enough.

Tolgee enables you to take and upload screenshot directly in the in-context translation dialog. So no more manual taking and uploading screenshots.

Localization platform included ✅

Tolgee is also localization platform, where you can manage all your localization strings. You can provide access to translators and they can translate the texts there.

If you have uploaded screenshots before, they know the context of the translations perfectly and can produce perfect results.

Isn't that hard to integrate? No it's not!

To get started, you can simply follow the integration guides provided in the platform.

Login to Tolgee Cloud or use your self hosted Tolgee instance.
Create a new project by clicking Add button in the top right. Fill the project name.

Optionally, you can add multiple languages to translate your app into.
Select Integrate from side menu, choose React (Vite) and generate an API key with all scopes checked.

Success! 🎉 Now you just have to follow the integration guide.

Let's integrate it into React App

Generate brand new React App and open it your favorite editor

npm create vite@latest tolgee-hello-world -- --template react-ts
# follow the vite guide

Install Tolgee packages ⬇️
```
npm install @tolgee/react
```
Add Tolgee properties to you development .env file env.development.local by copying it from the integration guide
```
VITE_APP_TOLGEE_API_URL=https://app.tolgee.io
VITE_APP_TOLGEE_API_KEY=<your API key>
```
Wrap your App component in main.tsx with TolgeeProvider component. Again, you can copy it from the integration guide.

Go to App.tsx and replace all the crap with simple "Hello world!" message.

import './App.css';

function App() {
  return (
    <div className="App">
      <h1>Hello world!</h1>
    </div>
  );
}

export default App;

Wrap the "Hello world!" with <T> component and add keyName prop.

import './App.css';
import { T } from '@tolgee/react';

function App() {
  return (
    <div className="App">
      <h1>
        <T keyName="hello_world">Hello world!</T>
      </h1>
    </div>
  );
}

export default App;

Let's run the App in the browser and see the magic! 🪄

Hold your ALT key and move your mouse over the text. It should be highlighted.
When you click it, dialog opens and you're able to edit the text or generate screenshots.

After you hit the update button, your Hello World! text will be immediately changed to the new value!

Congratulations! You're done! 🎉🎉🎉

Now you are able to translate your React applications. To learn more about Tolgee or to find out how to translate more complicated cases, visit our docs.

Tolgee - Developer friendly localization tool

Tolgee helps teams localize apps effortlessly. We make translation simple with real-time updates and easy integration into your workflow.

Say goodbye to complex file management and focus on building great products. Fast, smooth, and built for devs.

If you like this tutorial, please help us with a star. It would help us to create more articles like this 💖

Star the Tolgee repository ⭐

Overriding dependency version in Spring Boot

Jan Cizmar — Sat, 14 Oct 2023 13:58:50 +0000

Do you know that feeling when you spend hours trying to do something without any luck and then you find out that the solution could not be easier? Well, that just happened to me. I was trying to upgrade the Hibernate version in our Spring boot app.

What doesn't work

I tried to exclude the dependency from spring boot and include the desired one the standard gradle way. With no luck...

    implementation ("org.springframework.boot:spring-boot-starter-data-jpa"){
        exclude group: 'org.hibernate.orm', module: 'hibernate-core'
        exclude group: "org.hibernate.orm", module: "hibernate-jpamodelgen"
    }
    implementation "org.hibernate:hibernate-core:$hibernateVersion"

After hours of trying to diagnose why I always got the version included in Spring Boot, I found out that there is the Spring Boot dependency management plugin. That's the plugin which handles all the spring boot versions and enforces the versions defined by spring boot.

What works

Fortunately, there is a way to override the version. And it's super easy.

You just need to specify the version in your build.gradle.

ext['<dependency>.version'] = '6.0.9'

or using properties.gradle:

spring-framework.version=6.0.9

as stated here in the Spring docs.

And voilà! It works! You can find the list of the version properties you can override here.

Hope this helps future travelers who will struggle with the same.

Thanks for reading, and please consider using and staring Tolgee platform on GitHub ⭐️ - a tool healing your localization pain.

Tolgee: i18n revolution for modern JS frameworks; And it is open-source

Jan Cizmar — Mon, 19 Sep 2022 10:44:12 +0000

Hi all,

I am Jan from Tolgee. A few years ago I had an idea to create a tool that enables me and my team to simplify the localization/i18n process and enable non-programmers to modify localization strings without Git knowledge and anything. I started to develop the project and now, a few years after, we have a production-ready working solution. So let me explain what it does and why you should consider using it.

What is internationalization/localization/i18n/l10n?

Basically, if you're using some i18n library, enabling you to translate strings (like button labels, page titles, etc.) in your app to different human languages, you are doing internationalization. If you are actually translating the strings or preparing your app for usage in a specific region, you are doing localization. The i18n / l10n are just abbreviations for these two terms, where 18 and 10 mean the number of characters omitted in the word.

(simplified explanation)

What's Tolgee?

Tolgee is a localization platform that also provides its own integration libraries. It provides many great features making the app localization a piece of cake.

There are many i18n libraries out there. Why should I use Tolgee?

Tolgee can do a lot more than just traditional i18n library. It doesn't only provide the different strings for different languages, but it also enables you to change the strings directly in the app you are currently working on. It also allows others to translate/modify/fix strings in your app. Even your grandma, your aunt, or your Armenian friend from studies abroad.

It is also a localization platform, where you can translate your strings, while it suggests results from various third-party translators like Google Translator or DeepL.

It also enables developers to provide screenshots from the app in one click, so translators know the context and don't provide wrong translations. Which happens a lot btw.

And much more...

Why there are wrong translations on the Internet?

In most cases, it's because translators don't know the context of what they're translating. They see just the source string, but they don't see what's around it. So they have to guess the context, which leads to extremely wrong results. Let me explain with an example.

I am a Czech native speaker so I am using Netflix App translated to Czech. Once I opened the login page of the app. There was a password field and on the right side of the field there was a button labeled "POŘAD" which translated from Czech back to English means "TV SHOW". The designers of the app definitely didn't label their password showing the button "TV SHOW", they labeled it "SHOW". But the translators didn't know that they were translating a button for showing a password. They saw just the string "SHOW" and they were translating the Netflix app, so they guessed. And they guessed wrong.

There are many occurrences of wrong translations like this and the only way how to avoid this is to provide the context to your translators. But taking a screenshot or providing a text description to each label can be annoying.

How does Tolgee help me to have my app perfectly translated?

The operation of providing context has to be easy. Otherwise, developers won't do it. That's why Tolgee enables you to provide a screenshot with a highlighted string to translate with a single click. In the same dialog, where you can modify your localization strings, you can let Tolgee automatically take the screenshot from your App and highlight the string to be translated. This operation takes less than a few seconds. So the developers won't be annoyed by that.

How does it help developers? (The ALT+click magic)

There are various dev Tools for various things. You have React Dev tools, there are Angular dev tools, there are dev tools for state management libraries, etc. Tolgee brings dev tools for localization. When you click a translation string in your app with the ALT key, Tolgee dev tools open and you can translate your string. You never have to edit a .json/.po or other localization data files. The only thing you have to do is ALT + Click the string.

Cool. But how does it work?

In the development mode of the App, the strings are fetched from Tolgee API. If you modify the string or add a new key, the key is saved in the Tolgee Platform. So in development mode, you are working with remote data. That's basically it.

So my App relies on Tolgee Servers?

No! For the production build, you can export the translations from the API and store them as a static asset. So your app doesn't fetch anything from Tolgee API when it's used in the production environment.

So I have to export the string from Tolgee every time I change a string?

No! You can do that automatically in the CI/CD pipeline when your app is built. Or whenever you wish. We are also working on Tolgee CLI, which will help you with tasks like this.

My mama speaks Spanish. Can she translate the strings when my app is deployed?

Yes! She can use (the Tolgee Tools Chrome plugin)[https://chrome.google.com/webstore/detail/tolgee-tools/hacnbapajkkfohnonhbmegojnddagfnj] to enable the dev tools also in deployed App. Then she can translate it directly in the app.

What frameworks are supported?

Tolgee has integrations for React, Angular, Vue, Svelte, Next.js, Gatsby, and others. Learn more here.

How long does it take to integrate?

The integration is very fast! You can do it in seconds. It doesn't take longer than other libraries. There are integration guides in the docs and also in the platform. If you get lost you can just contact us via chat on our website or via our community Slack channel.

Does it work with SSR?

Yes. There are guides in the docs on how to make it work with popular SSR frameworks.

Can I self-host the platform?

Yes. It's open source and you can self-host the platform. Just follow the docs.

I am using i18next I don't want to migrate

No problem. Tolgee has also SDK for i18next. So you can use it with it. Here are the docs.

Typescript?

The @tolgee/core and all the JS integrations are written in Typescript so the API is typed. You don't have to install @types/.... The types are provided with the npm packages. We also plan to provide type-safety for the translation keys, similar to typesafe-i18n, in the future.

What technologies are used?

For the platform, we use Kotlin/SpringBoot on the backend and Typescript/React on the front end. For the integrations, we use Typescript if we can.

Nice. So what do you want?

It would be nice if you try Tolgee and give us some feedback. Also, we would be pretty happy to get some GitHub stars from you.

Thanks for reading!

Let this script type instead of you when you record a video of your browser ⌨

Jan Cizmar — Wed, 07 Sep 2022 12:29:37 +0000

I was working on cool gifs for Tolgee's new readme, where we show how simply you can modify a localization string in your App. But when I need to type something into input, I always make like 5 mistakes and my typing is not very nice to look at. So I created a script that types the string instead of me when I hit a specific shortcut. Now I use this to record videos, where I have to fill in some input, and I don't want to record it like 1000 times because I was typing inconsistently.

It can be useful for some pranks if you extend this. But let's leave this to your imagination.

How does it work?

So how does it work? It takes the array of strings. When I hit ctrl + h for the first time, it iterates over characters in the first string and modifies the value of the currently focused input by adding the current character. It waits 30ms between every character addition. When I hit the shortcut a second time, it does the same thing with the second string.

React issue

When you just modify the value property of an input element, React doesn't trigger your onChange listener and so the value is not changed, since React state is not updated. To trigger the onChange event listener you have to also dispatch input and do some other stuff you can read
about [here (https://stackoverflow.com/questions/30683628/react-js-setting-value-of-input/52486921#52486921).

The script

The script (I call it typescript 😄):

(() => {
  const strs = ["This is text...", "This is another text."];
  let hits = 0;
  window.onkeyup = async (event) => {
    if (event.ctrlKey && event.key === "h") {
      const input = document.activeElement;
      for (const char of strs[hits]) {
        if (input.value !== undefined) {
          setNativeValue(input, input.value + char)
        }
        await new Promise((resolve) => setTimeout(resolve, 30))
      }
      hits++;
    }
  }

  // Boring part starts here
  // It makes it working with react.js apps
  function setNativeValue(element, value) {
    let lastValue = element.value;
    element.value = value;
    let event = new Event("input", {target: element, bubbles: true});
    // React 15
    event.simulated = true;
    // React 16
    let tracker = element._valueTracker;
    if (tracker) {
      tracker.setValue(lastValue);
    }
    element.dispatchEvent(event);
  }
})()

How to use it

Copy the script and modify the strings to be typed
Copy the modified script
Go to the console of developer tools in your browser and paste the script
Hit enter
Focus an input and hit ctrl + h
Your text is being typed

Tolgee is an open-source solution for software localization i18n. Translate your applications and save up to 90% of time needed for localization! Tolgee.io

Star our GitHub repository [tolgee/tolgee-platform (https://github.com/tolgee/tolgee-platform) ⭐⭐⭐!

All you need to know to deal with user avatars 👤 in React

Jan Cizmar — Mon, 07 Feb 2022 09:02:24 +0000

Most of the information systems using user authentication also work with some kind of avatars - images enabling other users to see who commented, posted or made anything else in the system. When we want to be able to show user avatars, we need to enable users to upload their avatar or generate some default.

In this article I am going to show you how to:

generate user avatar by their unique ID using jdenticon
select avatar from file
crop selected avatar using cropper.js and react-cropper libraries

Generating default avatar

When the user hasn't selected their own avatar, we have few options what to show instead of it. We can show nothing, use some placeholder image 👤 or generate some pretty cool image. 😎

There are multiple avatar generators in npm. I chose jdenticon because I like the images it produces.

You can also find this nice icon designer in their docs, so you can customize the output. But I am going to stick with defaults.

So let's see how to use the library to generate the image.

import { ComponentProps, FC, useState } from 'react';

export const AutoAvatar: FC<
  ComponentProps<'img'> & { userId: number; size: number }
> = ({ userId, size, ...imgProps }) => {
  const [base64, setBase64] = useState(undefined as string | undefined);

  // using dynamic import to save some loading
  import('jdenticon').then(({ toSvg }) => {
    const svgString = toSvg(userId, size);
    const base64 = Buffer.from(svgString).toString('base64');
    setBase64(base64);
  });

  return base64 ? (
    <div style={{ backgroundColor: 'rgb(225,225,225)', display: 'flex' }}>
      <img
        {...imgProps}
        src={`data:image/svg+xml;base64,${base64}`}
        alt={'User Avatar'}
      />
    </div>
  ) : (
    <div style={{ width: size, height: size, display: 'inline-block' }}>
      Loading...
    </div>
  );
};

What I am doing here is loading the jdenticon library using dynamic import. The library has approx. 45 kb, so it is good idea to let webpack download it dynamically just when it's needed.

When it's loaded, I let the library produce svg by user ID. The library works similarly as good hash function so for near values it produces completely different results.

If you don't trust me, you can play with that here.

When it's generated I am converting the result to base64 to use it in img src attribute.

That's it. Avatar generated! 🥳

Letting user select an avatar

To let user select an avatar, we can simply use input element with file type attribute.

<input
  type="file"
  accept="image/png,image/jpeg,image/gif"
/>

But this input is pretty ugly. So I am going to hide it and provide my own cool button instead of this. Then I can trigger
click on this input to open the system file selection dialog.

import React, {createRef} from "react";

export const ImageSelect = () => {
  const fileRef = createRef<HTMLInputElement>();

  const onFileInputChange: React.ChangeEventHandler<HTMLInputElement> = (e) => {
    console.log(e.target?.files?.[0]);
  }

  return (
    <>
      <input
        type="file"
        style={{display: 'none'}}
        ref={fileRef}
        onChange={onFileInputChange}
        accept="image/png,image/jpeg,image/gif"
      />
      <button
        onClick={() => fileRef.current?.click()}
      >Cool Button
      </button>
    </>
  )
}

Like this, we can use any event to open the file selection. When the user selects some file, it is printed to the console. Now we would be prepared to upload the file to backend. But that would be lame. Let's also crop the image! 🎈

Cropping the image

To provide a bit more comfort to our users it would be nice to enable them to crop the image before they actually upload it. This can be done using cropper.js and its React wrapper react-cropper.

import React, {createRef} from "react";
import {Cropper, ReactCropperElement} from "react-cropper";
import 'cropperjs/dist/cropper.css';

export const ImageCrop = () => {
  const cropperRef = createRef<ReactCropperElement>();

  return (
    <Cropper
      src="<the iamge src>"
      style={{height: 400, width: 400}}
      autoCropArea={1}
      aspectRatio={1}
      viewMode={3}
      guides={false}
      ref={cropperRef}
    />
  )
}

What does the configuration do?

autoCropArea=1 - selects whole image by default
aspectRatio=1 - makes it 1:1, so it is square
viewMode=3 - makes the image to cover cropper size and disables selecting empty areas by moving out from canvas
guides=false - removes tiny lines, which I found unnecessary for croping avatars

So now it would be nice to get the actual cropped image. We can do it this way:

import React, {createRef, useState} from "react";
import {Cropper, ReactCropperElement} from "react-cropper";
import 'cropperjs/dist/cropper.css';

export const ImageCrop = () => {
  const cropperRef = createRef<ReactCropperElement>();
  const [cropped, setCropped] = useState(null as string | null);

  const onSaveClick = () => {
    const imageElement: any = cropperRef?.current;
    const cropper: any = imageElement?.cropper;
    setCropped(cropper.getCroppedCanvas().toDataURL())
  }

  return (
    <>
      <Cropper
        src={"https://picsum.photos/500/300"}
        style={{height: 400, width: 400}}
        autoCropArea={1}
        aspectRatio={1}
        viewMode={3}
        guides={false}
        ref={cropperRef}
      />
      <button onClick={onSaveClick}>Crop</button>
      {cropped &&
        <img src={cropped} alt={"It's cropped"}/>
      }
    </>
  )
}

If we would like to get the image for uploading, it would be better to use

cropper.getCroppedCanvas().toBlog()

Which provides a blob which we can use to create a file to upload.

Depends, for what we like to use the result. If we would like to upload it, blob is what we are looking for. To just show the image dataUrl is our choice.

Cool! So now we can also crop the image. Now, let's combine it all together!

import React, {createRef, useState} from 'react';
import './App.css';
import {Cropper, ReactCropperElement} from "react-cropper";
import 'cropperjs/dist/cropper.css';
import './roundedCropper.css';

// this transforms file to base64
const file2Base64 = (file: File): Promise<string> => {
  return new Promise<string>((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result?.toString() || '');
    reader.onerror = (error) => reject(error);
  });
};

const App = () => {
  // ref of the file input
  const fileRef = createRef<HTMLInputElement>();

  // the selected image
  const [uploaded, setUploaded] = useState(null as string | null);

  // the resulting cropped image
  const [cropped, setCropped] = useState(null as string | null);

  // the reference of cropper element
  const cropperRef = createRef<ReactCropperElement>();

  const onFileInputChange: React.ChangeEventHandler<HTMLInputElement> = (e) => {
    const file = e.target?.files?.[0];
    if (file) {
      file2Base64(file).then((base64) => {
        setUploaded(base64);
      });
    }
  }

  const onCrop = () => {
    const imageElement: any = cropperRef?.current;
    const cropper: any = imageElement?.cropper;
    setCropped(cropper.getCroppedCanvas().toDataURL())
  }

  return (
    <>
      <div className="App">
        {
          uploaded ?
            <div>
              <Cropper
                src={uploaded}
                style={{height: 400, width: 400}}
                autoCropArea={1}
                aspectRatio={1}
                viewMode={3}
                guides={false}
                ref={cropperRef}
              />
              <button onClick={onCrop}>Crop</button>
              {cropped && <img src={cropped} alt="Cropped!"/>}
            </div>
            :
            <>
              <input
                type="file"
                style={{display: 'none'}}
                ref={fileRef}
                onChange={onFileInputChange}
                accept="image/png,image/jpeg,image/gif"
              />
              <button
                onClick={() => fileRef.current?.click()}
              >Upload something!
              </button>
            </>}
      </div>
    </>
  );
}

export default App;

When user selects an image, the cropper component is rendered. When user hits the crop button, the resulting cropped image is shown. That's all. Easy-peasy.

Making the selection rounded

If you would like to use the avatars rounded, you would probably like to make also the selection rounded.

To do so, we have to style the cropper elements.

.cropper-crop-box, .cropper-view-box {
    border-radius: 50%;
}

TL;DR

In this article I explained how to generate default avatar using jdenticon library and how to select an image file and also, how to enable user to crop it using react-croper library.

Tolgee is an open-source solution for software localization i18n. Translate your applications and save up to 90% of time needed for localization! Tolgee.io

Super fast React Localization 🌍 (i18n) with i18next and Tolgee 🐁

Jan Cizmar — Mon, 24 Jan 2022 14:36:53 +0000

So you develop an app in React and you want many users to use it, right? To make your app usable for users in foreign countries, you have to translate your App to their languages. 🇬🇧 🇨🇳 🇮🇹 🇪🇸 🇫🇷

In this article, I am going to show you, how to integrate i18next and Tolgee into your project and how easy and fast you can translate a React app using these tools.

Tolgee has also its native integrations. Which are a bit easier to set up, so if you're not used to i18next, maybe it would be easier for you to [start with those (http://tolgee.io/docs/web/using_with_react/installation/docs/web/using_with_react/installation).

What is i18next?

i18next is a library enabling you to localize your app. Basically, you are calling methods of this library providing keys to be translated. The methods return value in specified language retrieved from localization files. There is much more about i18next, but let's keep it simple for this tutorial. You can read more about i18next here.

OK! And what is Tolgee?

Tolgee is an open-source tool combining localization platform and integrations to provide a simple way to translate the web
applications for both developers and translators. 👨‍💻👩🏻‍💻🧖🏼👩🏻‍💻🧖🏼

Tolgee Localization Platform is a place, where you can manage all your localization strings in the simple UI. It's made to simplify the localization process as much as possible. With Tolgee you can translate the localization strings directly in the application you develop without editing localization data files. You can also automatically generate screenshots from your app, which can be used in the future by translators of your project.

So let's dive in to the hacking!

Bootstrapping the App 🔥

I am going to use Create React App for this, since it's the simplest way to bootstrap a React app.

I am going to use Typescript, but if you're JavaScript purist, remove the --template typescript part. Open your terminal and command it to execute...

npx create-react-app@5.0.0 i18next-tolgee-demo --template typescript && cd i18next-tolgee-demo

Then install packages necessary for the localization (i18n).

npm install react-i18next i18next-icu i18next @tolgee/i18next @tolgee/ui

If the process succeeded we are prepared to start hacking! 😎

Open the project in your favourite editor, and go to App.tsx and replace all the crap with this:

import React from 'react';
import './App.css';

function App() {
  return (
    <div className="App">
      <h1>
        Hello world!
      </h1>
    </div>
  );
}

export default App;

We don't need the default CRA content.

Setting up a Tolgee project

To get started, we are going to need a new project in Tolgee Platform.

Login to Tolgee Platform or use your
self-hosted Tolgee instance.
Create a new project by clicking Add button in the top right. And fill the project name.

Optionally, you can add multiple languages to translate your app into.

Expand your user menu in top right corner and choose API keys.

Hit plus button, then leave all checkboxes checked and click save.
Done. You have obtained your API key!

Configuring i18next with Tolgee

First, let's create a file called .env.development.local in the project root. This file contains our Tolgee configuration.

REACT_APP_TOLGEE_API_URL=https://app.tolgee.io
REACT_APP_TOLGEE_API_KEY=<your_api_key>

Then go to index.tsx and configure i18n object from i18next library.

import {withTolgee} from '@tolgee/i18next';
import i18n from "i18next";
import ICU from 'i18next-icu';
import {initReactI18next} from "react-i18next";

withTolgee(i18n, {
  apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
  apiKey: process.env.REACT_APP_TOLGEE_API_KEY,
  ui: process.env.REACT_APP_TOLGEE_API_KEY
    ? require('@tolgee/ui').UI
    : undefined,
})
  .use(ICU)
  .use(initReactI18next)
  .init({
    supportedLngs: ['en', 'cs'],
    fallbackLng: 'en'
  });

This sets Tolgee as translation provider for i18next and enables ICU message formatter. Change supportedLngs to language tags you created while creating project in Tolgee platform.

Then wrap your <App/> component with Suspens component.

<Suspense fallback={<div>Loading...</div>}>
  <App/>
</Suspense>

So when translations are loading, fallback is rendered.

Translating on steroids 💪

Now we can start translating. Let's go to App.tsx again and obtain t function by calling useTranslation hook. Then use the t function in the returned JSX.

function App() {
  const {t} = useTranslation()

  return (
    <div className="App">
      <h1>
        {t('hello_world', 'Hello world!')}
      </h1>
    </div>
  );
}

The first parameter is the translation key, which is a unique identifier of the string. Normally I would recommend to also provide some information about the placing of the string in the app. So if the text is for example placed in settings, it would be good practice naming it settings.hello-world. The second parameter is default value, which is going to be rendered, when no translation is provided in localization data.

Now start the dev server or restart it, if you already started, so the .env properties are refreshed.

npm run start

After project is built, open it in the browser. You should see Hello world! 👋 message.

Now let's do some the magic. 💫

Click on the "Hello world!" text while holding Alt key or ⌥ key on Mac.

Quick translation appears if everything is configured well. If not, double-check your .env.development.local and check the properties are accessible in the browser by printing them to console using console.log().

In the quick translation dialog, try to change the value to something else like "Hello universe!" and hit save. See? The text was changed in the DOM as well.

String saved or edited in the translation dialog is stored in the platform, so you can edit there as well.

You can also edit more languages in the quick translation dialog. Also, you can take screenshots, which can be later used by translators, translating your strings in Tolgee platform.

Your mama can translate like this 👵

Translating using this dialog or Tolgee platform is very simple so anybody from your team or even your mama can translate your app like this. So when you would like to save some time, you can just provide access to the platform or/and to the app in development mode and let anybody translate it.

But let's get back to the code.

Switching the language

To be able to switch the language, create following LanguageSelector component.

import React from 'react';
import {useTranslation} from 'react-i18next';

export const LangSelector: React.FC = () => {
  const {i18n} = useTranslation();

  return (
    <select
      className="lang-selector"
      onChange={(e) => i18n.changeLanguage(e.target.value)}
      value={i18n.language}
    >
      <option value="en">🇬🇧 English</option>
      <option value="cs">🇨🇿 Česky</option>
    </select>
  );
};

And use it in the App component...

<div className="App" style={{padding: 40}}>
  <LangSelector/>
  <h1>
    {t(`hello_world`)}
  </h1>
</div>

Great! Now you are able to switch the language!

Preparing for production

In production mode you don't want to leak you API key. You want your translations to be part of the production build. There are multiple options to obtain your exported localization files.

Option 1: Using Tolgee Platform

Open your project in the Tolgee Platform
Click on "Export" item in the side menu
Hit "Export as zip of .json files" button
Download of exported data starts immediately

Option 2: Using API endpoint

If you have curl installed in your system, you can download the data using it.

curl "https://app.tolgee.io/api/project/export/jsonZip?ak=<YOUR API KEY>" \
--output data.zip
unzip data.zip
delete data.zip

This is useful, when you would like to automate localization data downloading in our CI/CD workflow.

Using the data

To use your exported data, store them into src/i18n folder. So your project structure would look like this:

src
...
├── App.tsx
├── LangSelector.tsx
├── i18n
│   ├── cs.json
│   └── en.json
├── index.css
├── index.tsx
...

Now, lets provide the data to Tolgee. There are multiple ways, how to do so described in docs. But I am going to provide them as imported static objects, which is good option, since the App is small and there are not many translations yet.

Go to the index.tsx file and import the localization jsons:

import enLang from "./i18n/en.json"
import csLang from "./i18n/cs.json"

And then provide them to Tolgee config.

withTolgee(i18n, {
  apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
  apiKey: process.env.REACT_APP_TOLGEE_API_KEY,
  ui: process.env.REACT_APP_TOLGEE_API_KEY
    ? require('@tolgee/ui').UI
    : undefined,
  staticData: {
    en: enLang,
    cs: csLang
  }
})
  .use(ICU)
  .use(initReactI18next)
  .init({
    supportedLngs: ['en', 'cs'],
    fallbackLng: 'en'
  });

To test it works, you can comment out the apiKey param. App should be translated without fetching the data from Tolgee API.

Congrats! 🎉 Now you are able to speed up your localization process!

TL;DR

Tolgee is an open-source tool, simplifying localization process and removing unnecessary tasks
It enables you or your colleagues to modify translated string in the context of developed web application
Tolgee is also a localization platform, where you can manage all your translations
If you like our project, please star our projects on GitHub
- github.com/tolgee/server ⭐
- github.com/tolgee/js ⭐
To read more about i18next Tolgee integration, visit Tolgee docs

Testing file Download ⬇️ in Spring 🍃 Boot

Jan Cizmar — Sat, 15 Jan 2022 11:46:41 +0000

It's pretty common case to generate file on the backend and let user to download it. But how to test it? I found testing of this scenario not quite well documented. So here's my bit.

We have to use getAsyncResult method from MvcResult interface, which enables us to retrieve content provided using StreamingResponseBody. So first, let's look how to generate file in the controller.

I am going to use Kotlin btw. 😎

Streaming body with `StreamingResponseBody`

Let's say we want to enable user to download some fine, which is not very small. For the demo I will just generate a text file containing a lot of a characters.



@Controller
@RequestMapping(value = ["/api/v1/03/get-file"])
class FileProducingController {
    @GetMapping(value = [""], produces = ["application/text"])
    fun export(): ResponseEntity<StreamingResponseBody> {

        return ResponseEntity
                .ok()
                // set a filename
                .header(
                        "Content-Disposition",
                        """attachment; filename="%file.txt""""
                )
                .body(
                        // stream the body
                        StreamingResponseBody { out: OutputStream ->
                            val text = "a".repeat(1000000)
                            out.write(text.toByteArray())
                            out.close()
                        }
                )
    }
}

So what I am doing here is that I am setting the file name, which is the default when user downloads it in a browser. And then I am writing the text to the StreamResponseBody's output.

Finally the testing part

So when I want to test it I have to do this.



@SpringBootTest
@AutoConfigureMockMvc
internal class FileProducingControllerTest {
    @field:Autowired
    lateinit var mvc: MockMvc

    @Test
    fun `produces correct body`() {
        val result = mvc.perform(
                MockMvcRequestBuilders.get("/api/v1/03/get-file")
        )
                .andDo { it.asyncResult }
                .andReturn()
        val content = result.response.contentAsString
        assertEquals("a".repeat(1000000), content)
    }
}

Notice the part with it.asyncResult. Without this part the test would fail. There will be just part of the output in the response's contentAsString result, because it won't wait for the stream to end. You can try this by removing the part and see it fails.

Tolgee is an open-source solution for software localization. It saves developer's time. Go to Tolgee.io and have fun!

🎈Using param object in Spring 🍃 Data JPA query

Jan Cizmar — Wed, 12 Jan 2022 16:46:18 +0000

Spring Boot JPA repositories are very simple and useful approach how to get data we need for our business logic. Instead of implementing methods, which would execute queries, we can just annotate repository methods with @Query annotation. Spring automatically implements these methods using proxies and we don't have to care, what happens under the hood.

We can simply pass variables by defining them as parameters of the annotated methods and using them in the query with : prefix.



  @Query("from Project p where p.user = :userAccount")
  fun getAllUserProjects(userAccount: UserAccount): List<Project>

This is great, but what we need to pass more params to the query, like more complex filters? Can we do that using object encapsulating these parameters? Yes we can! Spring supports also using SpEL in the JPA Queries!



  @Query("""from UserAccount 
    where u.firstname = :#{#customer.firstname}""")
  fun findCoolUsers(
    @Param("customer")
    customer: UserAccount
  ): List<UserAccount>

This is very useful, when we need to pass many parameters to our query and we don't want to define many function parameters.

Tolgee is an open-source solution for software localization. It saves developer's time. Go to Tolgee.io and have fun!

Creating Custom Hibernate Dialect

Jan Cizmar — Tue, 11 Jan 2022 08:30:41 +0000

While working with Hibernate's HQL and Criteria Queries I was missing some features of PostgreSQL which would help. I don't want to write native queries for this. Once I use Hibernate I should stick with Hibernate. Right?

One of the features I was missing in Hibernate's default Postgres dialect was similarity function, which returns how two strings are different on 0 to 1 scale. So let's see, how to create our own Hibernate dialect to be able to use similarity function in HQL or Criteria Queries.

The Dialect class

First of all, let's create a class with the dialect. I am using Kotlin btw. 😎

package io.tolgee.dialects.postgres

import org.hibernate.NullPrecedence
import org.hibernate.dialect.PostgreSQL10Dialect
import org.hibernate.dialect.function.SQLFunction
import org.hibernate.engine.spi.Mapping
import org.hibernate.engine.spi.SessionFactoryImplementor
import org.hibernate.type.FloatType
import org.hibernate.type.Type

class CustomPostgreSQLDialect : PostgreSQL10Dialect() {
  init {
    registerFunction(
      "similarity",
      object : SQLFunction {
        override fun hasArguments(): Boolean = true

        override fun hasParenthesesIfNoArguments() = false

        override fun getReturnType(firstArgumentType: Type?, mapping: Mapping?) = FloatType()

        override fun render(
          firstArgumentType: Type,
          arguments: MutableList<Any?>,
          factory: SessionFactoryImplementor
        ): String {
          return "similarity(${arguments[0]}, ${arguments[1]})"
        }
      }
    )
  }
}

Simple, right? In the constructor we just call registerFunction method accepting the function name parameter and object implementing SQLFunction interface, which I am implementing right in the place. Maybe in the future, when my CustomPostgreSQLDialect will grow I would extract this into separate class, but for now I am OK with this.

Since we are implementing interface, there are few methods we have to override. Their names are pretty self-explanatory. It tells Hibernate that

the function has arguments
it has Float return type
when HQL or CriteriaQuery is transformed to SQL it should be rendered like similarity(1st argument, 2nd argument)

The hasParenthesesIfNoArguments doesn't make any sense, because the function cannot work without arguments, so I set it false.

Enabling the dialect

Enabling the dialect is as simple as setting Hibernate prop dialect to dialect's absolute class name.

Since I am using Spring Boot, I have this in my application.yaml.

spring:
  jpa:
    properties:
      hibernate:
        dialect: io.tolgee.dialects.postgres.CustomPostgreSQLDialect

Testing time!

package io.tolgee.dialects.postgres

import io.tolgee.model.UserAccount
import io.tolgee.testing.assertions.Assertions.assertThat
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests
import org.testng.annotations.Test
import javax.persistence.EntityManager


@SpringBootTest
class CustomPostgreSQLDialectTest: AbstractTransactionalTestNGSpringContextTests() {

  @Autowired
  lateinit var entityManager: EntityManager

  @Test
  fun `similarity function works`(){
    // Hibernate queries doesn't work without FROM clause, so we have 
    // to create a dummy entity to select from
    entityManager.persist(UserAccount(username = "aaa", password = "aaaa", name = "aaaaa"))
    val query = entityManager.createQuery(
      "select similarity('I am so funny!', 'You are so funny!') from UserAccount"
    )
    assertThat(query.singleResult).isEqualTo(0.47619048f)
  }
}

TL;DR

Create your own Hibernate dialect when you need to use advanced features of your database system
It can be done just by extending another dialect and adding functions you need

Tolgee is an open-source solution for software localization. It saves developer's time. Go to Tolgee.io and have fun!

Running Spring Boot App and PostgreSQL in single container

Jan Cizmar — Mon, 10 Jan 2022 14:16:55 +0000

When developing self-hosted open-source service, which meant to be used by as many users as possible, you would probably want to provide a simple way how run your service. It should preferably work without any configuration so users can get it working as fast as possible.🔥

The simplest way to achieve this with Docker is running a Docker image with docker run command.

When your application needs database system to store its data, you have basically two options. Using multiple containers - one for the application and one for DB. Or you can go with embedding the DB service in the the same container with application. 📦

For deploying the application to the cloud, I recommend running it in multiple containers or use database managed by your cloud provider. In Tolgee we use Kubernetes for deploying our Application container and DigitalOcean's managed PostgreSQL DB, so we don't have to worry about the database cluster.

But for users who want to self-host it themselves, we also want to provide the simple docker run way which is going to work right away without setting up a database system or any other services. It just has to run! Now! 🏃‍♂️ 🏃‍♀️

So if you would like to run Tolgee, you can do it simply by running this command:



docker run -v tolgee_data:/data/ -p 8085:8080 tolgee/tolgee

Before, we supported H2 and Postgres databases at the same time. We used H2 database as a default, since H2 doesn't need to be run as external service. It is just Java library which can store the data in memory or in filesystem. However, H2 db doesn't satisfy our needs anymore, so we have to drop its support.🤷‍♂️

OK, but we want to keep the ability to run it in single container, so how to do that?

Tolgee is implemented in Kotlin which is JVM language, so we need JDK to run it. So we need to somehow combine JDK and PostgreSQL images and then find a way how to run both of the services in the same container properly.

Getting the Postgres DB to our JDK container 🍱

To create our Docker image, we are using Dockerfile based on openjdk:14-jdk-alpine image. So first thing we have to do is add a PostgreSQL DB to this image to have both JDK and Postgres prepared. To do so, I found official Postgres image sources and used their code to create my own image containing JDK and Postgres. Basically I just took their Dockerfile and docker-entrypoint.sh and replaced the FROM alpine:3.15 with FROM openjdk:14-jdk-alpine. Thats it. Now we have Postgres and JDK in the same image.

HERE is the Docker image source

Running multiple services in a single container 🏃‍♂️ 📦

Second, the harder part is to actually run the services in single container.

There are multiple options according to Docker documentation how to achieve this.

1. Creating a script running the services 📜



#!/bin/bash

# Start the first process
./my_first_process &

# Start the second process
./my_second_process &

# Wait for any process to exit
wait -n

# Exit with status of process that exited first
exit $?

This basically runs all the services and if one exits, the whole container exits as well. This is cool, but this is not optimal since we want to:

wait for Postgres to be started before running the app
configure whether the database service is enabled or not, so user can use their own external Postgres

So we would have to modify this script a lot or find a better solution. Luckily, there are some.

2. Supervisor 🥸

Supervisor is a tool which can run and manage multiple services. It has a lot of features like redirecting stdout and stderr, managing how many times the services should try to start, or whether should service be restarted when exited. This is all cool, but I found few drawbacks trying to get it working with Supervisor.

There is no option telling Supervisor to run service only if specific environment variable is set, so I would have to write a script for it
There is no way how to tell Supervisor to exit when one of managed services exits. The supervisor is still running even after all services exited, which is in contrary with Docker philosophy. Containers should be managed by Docker and Docker should control whether services are restarted or not.

3. Letting the Spring Boot App to start the PostgreSQL server

Finally, I decided to do it a similar way as GitLab does it. I am letting the Spring Boot App to run the Postgres server while creating the DataSource bean. So the Spring Boot App is in charge of managing the DB.

*** HERE you can find the relevant code

Configuration (PostgresAutoStartConfiguration.kt)

First, I created a configuration, which is conditional on property tolgee.postgres-autostart.enabled. This Configuration creates a DataSource bean manually. And before this bean is returned, it uses my PostgresRunner to run the Postgres DB.

The runner (PostgresRunner.kt)

This class handles the actual running of the Postgres executable. It does this:

It runs the Postgres initialization script, which is taken from Postgres official Docker image code
It starts a new thread which is redirecting Postgres output to Logger methods
It waits until Postgres is ready by trying to open Socket on Postgres port
It has preDestroy method annotated with PreDestroy annotation, which stops Postgres when Spring Application exits.

So that's it. This is how you can Embed Postgres into your application code! 🎉🎉🎉

TL;DR

When you develop self-hosted service you would like to provide a simple way how to run it without complicated configuration steps
So you want like to embed DB and Application into same container to enable users to run in with docker run command
First you have to create Docker image which is able to run your Application (JDK in our case) and contains also DB to store your data (PostgreSQL in our case)
Then you have to find a way to start both of the services in the single container
The best way I came up with is to run manage the PostgreSQL with the Java Application, so I can turn it on or of using externalized configuration

Tolgee is an open-source solution for software localization. It saves developer's time. Go to Tolgee.io and have fun!

🌎 Why you should prepare your project for localization (i18n) right now

Jan Cizmar — Tue, 30 Nov 2021 09:22:49 +0000

We always recommend preparing projects for localization as soon as possible. A lot of people, we are talking with, say that they are in early stage of development of their app and localization 🌎 is something they don't need right now.

Setting localization aside is not a good idea, and I am going to tell you why.

It's boring and repetitive task ⌛🔄

When localizing your application with a lot of strings already in code, the localization is going to be very painful 🩸 task. In that case you will have to go through all your code and wrap all the strings in the code with some component or method, depending on language or framework you use. This could be hundreds or thousands of strings to wrap and localization keys to come up with.

See this example:

<h1>My beautiful App</h1>

<button>Like it!</button>

We have a tiny little app with a headline and button, whatever the button does, it has a text in it. It has a text to be translated! 😎 To translate it we have to transform it to something like this.


<h1>
  <T key="my-app-headline">My beautiful App</T>
</h1>

<button>
  <T key="button-like">Like</T>
</button>

Think of the T element as something which is replacing the text with translated value when language changes.

Now imagine, you have a code with thousands of strings like this you have to go through and wrap every text with this kind of code. It's very hard to do something like this with find & replace tool, since you have to come up with the nice semantic key.

Missing strings 🎯

Going through your codebase and replacing all the strings is not that easy as it seems, there could be translations in the element content, in the attributes, it could be generated by the logic and provided though variables or function calls.

<h1 id="headline"></h1>
<script>
  const headline = document.getElementById("headline");
  if (isTheAppCool) {
    headline.textContent = "My cool App"
  } else {
    headline.textContent = "My App"
  }
</script>

What now? 🙈 While this code is provided in the script part, it's very simple to miss it and provide imperfect experience to your users.

Losing context

When translating the application to different languages, you'll probably reach a point, when you would like translators to translate your app. So you take localization data from your app and send them to translators. Then you expect perfect results, since you don't understand the foreign language. That's the reason, why you pay for translator, isn't it?

So you will provide file like this.

{
  "my-app-headline": "My beautiful App",
  "button-like": "Like"
}

But the translator don't have any context information about the texts. Where is on the page? What's the purpose of the button? What is the gender of the objects? Is this noun or verb?

How can you do better?

Simple. Just integrate localization as soon as possible. From the beginning prepare your app to be localized. As a Tolgee founder I would recommend you to use out solution 😁, but you can use any other library suitable for your framework or language.

React: react-intl, react-i18next or @tolgee/react
Vue: vue-i18next, vue-intl or @tolgee/vue
Angular: @angular/localize (native), angular-i18next, @tolgee/angular
Svelte: svelte-i18n, @tolgee/svelte

While using those tools, try to also store context of the keys in form of comments or screenshots, which you can provide to translators in the future.

How can Tolgee 🐁 help?

Preparing your app to be localized is always good idea and with Tolgee you can do it without much time cost, since your only task is to wrap the string with T component come up with a nice translation key. Then you can just go to your app and translate your string with ALT + Click. You can also automatically generate a screenshot from your App to provide the context to your future translators. If you would like to learn more about it, check our documentation 📚 or choose an integration library above and follow the tutorials. 📖

TL; DR

Prepare your app for localization now 😎
You'll avoid untranslated texts 🥳
Your page will be translated correctly ✅
You will not die due to bore of the repetitive replacing your strings ⚰️⚱️

If you like what we do, please star our GitHub projects. 🙏

Tolgee Server ⭐
Tolgee JS ⭐

Forem: Jan Cizmar

I have localized the best short-linking platform in the world

Prerequisites

What is Tolgee?

How to set up Dub.co on your local computer

How to configure Tolgee in a Next.js application

How to set up localization in Dub.co

How to translate your application content with Tolgee

Conclusion

I easily translated my React.js applications into multiple languages. Here is how... 🤯

What is Tolgee

In context translating 📖

Automatic Screenshot Generation 📸

Localization platform included ✅

Isn't that hard to integrate? No it's not!

Let's integrate it into React App

Congratulations! You're done! 🎉🎉🎉

Tolgee - Developer friendly localization tool

Overriding dependency version in Spring Boot

What doesn't work

What works

Tolgee: i18n revolution for modern JS frameworks; And it is open-source

What is internationalization/localization/i18n/l10n?

What's Tolgee?

There are many i18n libraries out there. Why should I use Tolgee?

Why there are wrong translations on the Internet?

How does Tolgee help me to have my app perfectly translated?

How does it help developers? (The ALT+click magic)

Cool. But how does it work?

So my App relies on Tolgee Servers?

So I have to export the string from Tolgee every time I change a string?

My mama speaks Spanish. Can she translate the strings when my app is deployed?

What frameworks are supported?

How long does it take to integrate?

Does it work with SSR?

Can I self-host the platform?

I am using i18next I don't want to migrate

Typescript?

What technologies are used?

Nice. So what do you want?

Let this script type instead of you when you record a video of your browser ⌨

How does it work?

React issue

The script

How to use it

All you need to know to deal with user avatars 👤 in React

Generating default avatar

Letting user select an avatar

Cropping the image

Making the selection rounded

TL;DR

Super fast React Localization 🌍 (i18n) with i18next and Tolgee 🐁

What is i18next?

OK! And what is Tolgee?

Bootstrapping the App 🔥

Setting up a Tolgee project

Configuring i18next with Tolgee

Translating on steroids 💪

Your mama can translate like this 👵

Switching the language

Preparing for production

Option 1: Using Tolgee Platform

Option 2: Using API endpoint

Using the data

TL;DR

Testing file Download ⬇️ in Spring 🍃 Boot

Streaming body with StreamingResponseBody

Finally the testing part

🎈Using param object in Spring 🍃 Data JPA query

Creating Custom Hibernate Dialect

The Dialect class

Enabling the dialect

Testing time!

TL;DR

Running Spring Boot App and PostgreSQL in single container

Getting the Postgres DB to our JDK container 🍱

Running multiple services in a single container 🏃‍♂️ 📦

1. Creating a script running the services 📜

2. Supervisor 🥸

3. Letting the Spring Boot App to start the PostgreSQL server

Streaming body with `StreamingResponseBody`