DEV Community: Štěpán Granát

How to remove Java from JavaScript

Štěpán Granát — Mon, 24 Oct 2022 08:57:13 +0000

As a React developer, I have a suspicion to JS classes usage. In React bubble, it feels like a bad practice when I see them somewhere.

However, recently I got a task to rewrite our @tolgee/core, which is VanillaJS, and so far, there have been classes everywhere. I somehow felt it is not right. But then I realized that I don't actually know how to replace classes outside of React. Hmm ...

Wait, what's wrong with the classes?

Classes are basically added syntax sugar which gives you the impression that you are working with a class based programming language when you are actually not. Classes in JavaScript are implemented differently from the others. My main complaints are these:

How this works is a cause of many issues, and correctly understanding it is not easy
Inheritance is becoming an outdated concept, and classes encourage you to use it
Private fields in classes are not supported everywhere yet, and their syntax is weird (and Typescript private fields are not really private)
Class instances don't play well with desctructuring assignment

Classes in JavaScript tried to bring it closer to traditional OO languages, but it didn't go all the way. So if you are used to OOP, you won't get a very good experience, and it will feel like JS is crappy language. But it doesn't have to be this way.

Like a fish out of water

In React, you don't need classes and even when you use external libraries, they usually don't require you to write classes. So it's easy to say, "classes are not necessary, just write functions" however, the second you step outside the React ecosystem, it's different.

As I realized this, it got me thinking: Why is that? How comes, that with React classes are not necessary?

State and lifecycle

If you write a complex system, you need a way how to store your state somewhere. React has a way how to treat the state in your components, and it provides you with a lifecycle, which defines when the internal state is created, modified, and destroyed. Notice that it's very similar to class instances. In a way, React component is conceptually very similar to a class as it gives you a frame where your code lives, and you can "hook" into its lifecycle.

I think that's what I'm missing, that's why it's not easy to replace classes in our core.

Classes without classes

So I have a justification for classes, but that would mean I have to live with their shortcomings. Do I need to use class, this, extends, and new like Java programmer? It somehow feels bad. I like the world of simple objects and simple functions. I like the simple world.

Let's try to "emulate" classes as React does.

One way is to separate methods from data. This is often used in languages that don't support classes (e.g. C).

// equivalent of constructor
function createCar(color) {
  return {
    color,
  };
}

// equivalent of methods
function setCarColor(car, color) {
  car.color = color;
}

This method works, but it has even more disadvantages than classes as it doesn't encapsulate the data. It neither supports inheritance nor provides any nice way to replace it. All the data are exposed outside, meaning anyone can modify anything without your knowledge. The lifecycle is not enforced, it's just convention.

Closure objects

I've come across a lecture from David Crockford, where he recommends using closure instead of class.

By far, the worst new feature in es6 is class. This one was strongly recommended by all the Java guys who have to write in JavaScript now and who don't want to learn a new language. This gives them the illusion of writing in a language that they think they already know.

-- David Crockford

If you look at it, it kind of reminds the definition of a React component.

function Car(color) {
  const state = {
    color,
  };

  function setColor(color) {
    state.color = color;
  }

  return Object.freeze({
    setColor,
  });
}

The principle of this is that you create a higher-order function that wraps your methods and state variables. This function serves as your constructor. Its content is inaccessible from outside by definition. Then you just return what you want to be publicly available in an object which is the only gate to your data. It nicely forces you to create getters and setters for everything.

Even though this object represents the "instance", the data are not stored directly in it, so we can freeze it with Object.freeze. Data are actually stored in the constructor closure, and in the instance, we only "leak" functions that we want to be public.

How about inheritance?

Instead of traditional inheritance, you can use composition here, as you can call any other constructors, and combine their methods in your new object.

function Car(color) {

  ...

  const { setSpeed } = Vehicle();

  return Object.freeze({
    setColor,
    setSpeed,
  });
}

I've always found class inheritance confusing, and this way is much more readable for me. It's also quite similar to how React allows you to compose hooks, so it feels familiar.

Even though I haven't seen this method used in many places, it feels quite natural to me. I like how I see exactly what is passed where. It also brings an advantage in code optimization as private methods are truly private (unlike Typescript private methods), so the optimizer can optimize them accordingly.

One simple advantage is that you can safely use the desctructuring assignment here, as we won't run into issues with binding and prototype chain.

// this is perfectly ok
const { setColor } = Car(...)

Seems good. What's the catch?

No catch, except ...

Usage with typescript is not as smooth as with classes. With classes Typescript knows how to work with them and
so if you create class Car you can then use type Car as an type annotation for it's instance. This is not possible
with functions. It is possible to infer type, but we need to be more explicit.

let car: ReturnType<typeof Car>;

Over time I've started using a convention that with every constructor I also export the type of the instance like this:

export function Car(...) {
  ...
}
export type CarInstance = ReturnType<typeof Car>

For some reason, Typescript has a major issue with recursion in objects. It breaks this system if you want to return the instance itself in any method (which is quite common practice for chainable objects).

export function Car(...) {
  const car = Object.freeze({
    ...
    addWheel: (...) => {
      ...
      return car
    }
  })
  return car
}

export type CarInstance = ReturnType<typeof Car>

If you build this file into Car.d.ts with tsc compiler (v4.8.4), it will produce something like this:

export declare function Car(...): Readonly<{
  addWheel: (...) => Readonly<any>;
}>;

export declare type Instance = ReturnType<typeof Tolgee>;

Notice that the recursive function type is reduced to any, which is quite sad. I couldn't find any way around this, only to type the function explicitly, which is not ideal, but in my usecase still acceptable. Let's hope it will get better in future Typescript versions. If influential people will pull the strings, maybe we'll get some improvement.

// Detect dark theme var iframe = document.getElementById('tweet-1579319192729186304-731'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1579319192729186304&theme=dark" }

The Typescript drawbacks are quite significant, however for my usecase they are still outweight by drawbacks of classes and their "inappropriateness" in JavaScript.

Conventions

I've quite naturally started using capitalized function names for the constructors. I've seen different approaches with make or create prefixes, but I like the simplicity better.

There is also no clear name for this whole convention, I've seen it called Crockford objects or Crockford classes, but I would prefer "Closure objects", so the name has some reference to its meaning.

Conclusion

Python enthusiasts use the word "pythonic" for constructions that feel natural to them. I would call this "javascriptic" if that would be a term, but even if it's not, I think you know what I mean.

PS: Check Tolgee.io and give us github stars

Original article was published on our blog.

Is Turborepo overhyped?

Štěpán Granát — Tue, 08 Feb 2022 08:01:23 +0000

Two months ago, I was looking for a solution how to speed up pipeline in our monorepo. As an immediate answer I found basically two alternatives Nx (from Google) and Turborepo as a new cool project from well known open-source author (Jared Palmer). I was immediately drawn towards Turborepo as it was really hyped everywhere. Also, it is quite minimalistic, simple to use and it looked like exact fit for our use-case. So I got into it.

What is Turborepo and why do we need it?

Turborepo is a build system for monorepos (multiple projects in one repository). We use monorepo in Tolgee, because we have multiple SDKs for different frameworks as separate NPM packages and it is very convenient to test and release them together, so monorepo is an ideal fit.

As with every monorepo we struggle to keep our building and testing pipeline fast. Turborepo is designed for this. Simply put, it keeps a cache of previous builds for each individual project (workspace) and if nothing changed in that project, it will just use the cache instead of rebuilding. It also automatically detects dependencies between the projects so it knows that if the dependency of one project changed that project needs to be rebuilt too.

It can be also used for testing as you can only run tests in projects which are affected by changes and it treats standard output as part of a cache so even if some test don't run Turborepo will output cached logs, so you see all the test results every time.

It is also able to run multiple commands in parallel, which is ideal for development when you need to watch code changes and rebuild on the fly.

Setting up

I was able to understand Turborepo docs quite quickly (as it's really short so far 😄). It took me a bit of trial and error to set everything up correctly as I needed to wrap my head around how exactly the caching works. I recommend spending some time experimenting with changes in different projects and checking if it works correctly as it takes some time to wrap around your brain. However, in the end, it is very satisfying, when you see colorful label "FULL TURBO", when everything is taken from cache and no real build is necessary.

One little caveat was that we are using lerna, which has it's own definition for workspaces, however Turborepo requires the definition to be in package.json, which causes issues with npm install command as npm now also supports workspaces, but is installing dependencies differently than we need. I didn't find a simple way how to get around this issue so at the end I use custom command for module installation, which first removes workspaces from root package.json, then performs all the installations with lerna and then returns the package.json to original state, not ideal but managable.

Where the real issues started

During my experiments I've noticed that sometimes not all dependant projects are rebuild as they should be. I found already reported issue about it and amazingly the next day it was fixed. Wow. I wanned to upgrade to next version but wait ... that's weird some error appeared during an installation.

Hmm, I found another reported error - it seems like it's broken when you install it with npm (yarn and pnpm works), that's unfortunate 😔. Luckily it was fixed in about 4 hours, so now everything worked fine and I've prepared and tested everything and submitted it for a review. However, my colleague writes me back in two hours that the process it hitting his CPU running on 100% (one core) and his machine is constantly overheating even when he's in development mode and not making any changes to the code! Another issue (already existing on GitHub), Agh!!

Even when the issue was fixed the next day, I wasn't really that confident about Turborepo as even though it was in version 1.0.xx it seemed more like beta or alpha version. However, now everything worked so PR was merged.

A few hours later I've noticed a weird thing. All our available GitHub runners were busy and I was not able to run a new task. It turned out that when some build failed Turborepo didn't finish the process but it was stuck and ran forewer. I had to manually stop all CI pipelines and roll back the release as this was a major problem.

Maybe I made a mistake

Hmm, seems like Turborepo is not in production-ready state. I was really pissed as I've already spent about 4 days with this and now I'm back where I was at the beginning. I've tried to switch to Nx, but compared to the Turborepo setup, everything was much more complicated - it has all the functions we need, but it's really blown and not elegant at all.

Or not?

I've let everything as it was and let the PR open for one month. Now I've returned to it and Turborepo is in version 1.1.xx and everything seems to work as expected. Ok, our pipeline is much faster and we now have much more elegant way how to run dev mode locally. However I still better run our main release pipeline without any caching as I want to be sure that something is not getting cached when it shouldn't be as that really could be a big problem and I know, that Turborepo can't be 100% trusted.

My conclusion

Turborepo is a really cool project. And it's not just cool, it's really necessary - there clearly was missing some tool like this as monorepos are more and more popular. Everyone was tweeting about using Turborepo is great and that it made his pipeline 10x faster, but nobody was mentioning these issues. The hype around it fooled me to use it prematurely, lose valuable time and in the and be bitter about it.

So, you know 🤷🏻‍♂️. Be careful about what is currently trending and don't let the shine blind you, when you are deciding what to use on production.

PS: Check Tolgee.io and give us github stars

Original article was published on our blog.

Taking localization to i18next level

Štěpán Granát — Mon, 17 Jan 2022 10:01:36 +0000

The i18next library is one of the most popular choices for formatting translations in React applications. We decided, that we want to improve the experience by offering an easy integration with Tolgee. Localization is now uniquely accessible as your translations can be managed through opensource platform, without wasting precious Dev time.

Why i18next?

The i18next is very versatile and extensible and supports basically all features that you need from i18n library.

I was attracted to i18next mostly because it's React extension supports React elements interpolation through Trans component.

It's basically a way how to use custom elements in translations - it's really helpful when you for example need to have a link in the middle of translation. Normally you would need to have 3 separate translations and use them like this:

<p>
  {t("key_1")}
  <a href="...">{t("key_2")}</a>
  {t("key_3")}
</p>

If we use Trans component we can do this with one translation:

<Trans i18nKey="key_1" components={{ Link: <a href="..." /> }} />

while translation looking like Text 1 <Link>Text 2</Link> Text 3.
We'll get correct result with link inside. This way you can use any React elements and they will just get injected by the translation as child.

Additional tools for i18next

There is also a quite rich family of additional plugins and tools, which can be very useful. One of them is ICU support for i18next, which comes in handy as that is go to format for Tolgee.

Another very useful utilities are static extraction tools, which can scan your code and reliably find all keys that you are using in your project. This can help you make sure that everything is translated or eliminate unused keys.

How to integrate with Tolgee

We provide package @tolgee/i18next, which provides a "bridge" for integration.

So we'll need to install it, together with i18next, ICU parser and tolgee UI:

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

import i18next from 'i18next';
import ICU from 'i18next-icu';
import { withTolgee } from "@tolgee/i18next";
import { UI } from "@tolgee/ui";

withTolgee(i18n, {
  apiUrl: "https://app.tolgee.io",
  apiKey: ...,
  ui: UI,
})
  .use(ICU)
  .init({
    lng: 'en',
    supportedLngs: ['en', 'fr'],
  })

Now you can manage your tranlsations through Tolgee platform, so anyone can do translate (not just Devs!). You also have the power of in-context translatins, so when you add new key, you can add initial translation directly through your app and quickly take screenshot, so everyone knows where the translation is located.

How it works?

The withTolgee function is using i18next plugin system of backends, processors and also attaches event listeners and modifies default settings. We use our invisible text technique for marking each translation through i18next processor, so in-context functionality works as expected.

TLDR: Tolgee acts as a translations source, using i18next for formatting and language management, while keeping in-context localization working.

I want to try this!

We have example applications for React and Vue and play around with them. If you connect them with Tolgee platform, you can see in-context localization in action.

Using invisible text for better localization

Štěpán Granát — Mon, 20 Dec 2021 09:09:35 +0000

Some time ago I've came across an article about inserting secret text into regular messages using invisible zero-width unicode characters. Now during my work on localization SDKs, I've found quite interesting use case for it.

Background

At Tolgee we are offering localization SDKs, which enable you to insert your translated keys into web application. One of our main selling points is that we offer in-context localization out of box. In-context localization means, that when you are in development mode, you can click on any translation and change the translation directly in the app.

To make this work, our SDKs need to somehow mark where the translations are. We might just search the DOM for occurrences of translations in given language, however that won't cover more advanced cases, when we for example need to support variables in translations. Then the easiest way is to wrap each translation with span element and give it some special attribute, so then we can find it. Easy peasy, no? Well there is a catch ... what if user needs to translate texts where you can't use HTML (e.g. element attributes)? Or what if the extra span element is not acceptable?

Why is context important?

When you translate the app, it's important that you see where exactly is the translation located as pure translation from one language to another can be incorrect in many cases. So we offer in-context translation directly in the App and we want this feature to work everywhere.

Text based solution

Our original solution was in these cases insert string with our special syntax instead of the translation itself. Then we would observe whole page with MutationObserver and when we encounter this "encoded" text we find parent element and store the information about the translation and replace this message with our translation. As we found out this approach works quite well, mainly because observer is triggered before changes are rendered to the page, so this whole replacement is invisible to the user.

However, we still run into problems sometimes. We usually want to run observer only on body, so if you update e.g. page title, so then you can see text which is completely broken. Also when you use it in cases, when you need to measure the width of an element right after you change it - this will cause you problems, because the element is containing different text, so the measurements will be different. We offer the user an option to turn wrapping off, but he needs to do that explicitly and then the in-context localization doesn't work. Not ideal.

The idea of invisible marks

I think you can already see how invisible marks might be useful to us. I'll get to how it works, but for now let's just imagine, we have ability to insert invisible information to any text and then retrieve it. We can now insert secrets into every translation. Same as with regular text we can still observe the DOM for changes and when we find this "watermark" we know which translation it's containing and in-context can work anywhere.

This also opens a way for 3rd party libraries for formatting, because these invisible characters act like regular part of the text, it shouldn't be affected by regular text transformations (in theory).

Here even if the translation doesn't get picked up by MutationObserver, the translation will still be readable and it won't influence anything visually.

How do we make text invisible?

The mechanism of invisible text is described in the mentioned article. So basically I've picked two zero width unicode characters "ZERO WIDTH NON-JOINER" (ZWN) and "ZERO WIDTH JOINER" (ZWJ), which are normally used for joining/separating multiple characters together. We can stack 8 of them together and we have a byte (ZWN = 0 and ZWJ = 1). We can literally take JavaScript string, convert it to bytes and turn it into an invisible message. This way we can even have unicode string inside an unicode string.

One caveat is that ZWJ causes two characters acting as one, so it might have effect on text surrounding it. In our use case when we use multiple ZWN and ZWJ are used in succession, only the last one is interpreted so my solution is to use one extra ZWN at the end of each byte, so it's always last and that should eliminate all side effects.

The fact that each secret byte is 9 characters long is making long texts extremely memory inefficient. So I've chose to assign each translation a number and then encode it as unicode character. This way I take advantage of utf-8 characters which can be 1-4 bytes long, so I have effective space about 1 million combinations, which is more than enough for one page and I'll use relatively small amount of invisible characters (in most cases 9 or 18 for one key).

Can I try this?

We've just shipped Tolgee version 3, where it is as an optional setting, so you can try it yourself. We'll see if we find any issues with this approach and if not, we'll probably make it default way for wrapping translations in Tolgee.

Conclusion

We hope that this approach could allow us to use third party i18n libraries (e.g. i18next) as an alternatives to our SDKs, while keeping in-context feature working.

PS: Check Tolgee.io and give us github stars

Original article was published on our blog.

Same logic in 4 major FE frameworks, how do they compare?

Štěpán Granát — Mon, 29 Nov 2021 15:34:37 +0000

In Tolgee.io we needed to implement integrations for all major frontend frameworks. I'd say, that this is quite a good opportunity to show a real world comparison between them and it will allow us to dive into a bit more advanced functionality.

Overall design

Tolgee is a localization platform. Our integration libraries have two purposes:

Display and format translations in the application + manage language changes
In dev mode allow "in-context" localization - which means, that user can edit translations directly in the app

So in dev mode our library needs to communicate with our server, but in production mode it will only deal with generated JSON files, containing translations.

General integration library architecture

Integration libraries provide tailored API for given framework and only need to React on translation/language changes, coming from core library.

Translating regular texts

Every integration needs to provide a way to translate regular texts on the page in form of special component, so user can simply use the component and we need to make sure, that correct translation is displayed (based on selected language). We are using ICU message format, which allows passing variables, so user can also pass named parameters, which are referenced in translation self and translation strings can look like You have {itemsCount} items in your cart. In ideal scenario we'd like something like this:

<T keyName="cart_content_key" parameters={{itemsCount: 5}}/>

My main working tool is React and so I use React as kind of reference implementation

Translating imperatively

Translations can occur not only directly as children in DOM elements, but also in parameters like title or aria-label. For these cases we can't use component, but we need some user callable function, which will translate the text for him imperatively. E.g.:

<div title={t('translation_key')}>...</div>

Source of data

We need a way to provide tolgee/core instance and ideally we don't want limit it for just one (user might want to use multiple different sources of translations in the same project). Ideal would be to provide the instance globally or to a subtree of components in the application (In React it's exactly what Context API does).

Implementation for React

In React we use context API to provide Tolgee instance to all children:

export const TolgeeProviderContext = React.createContext(null);

export const TolgeeProvider = ({config, children}) => {
  const [tolgee] = useState(new Tolgee(config));

  useEffect(() => {
    tolgee.run();
    return () => {
      tolgee.stop();
    };
  }, []);

  return (
    <TolgeeProviderContext.Provider value={{tolgee}}>
      {children}
    </TolgeeProviderContext.Provider>
  );
};

Now let's look how we can use Tolgee context in T component:

export const T = ({ keyName, parameters }) =>
{
  const {tolgee} = useContext(TolgeeProviderContext);

  // get initial value
  const [translated, setTranslated] = useState(
    tolgee.instant(keyName, parameters)
  );

  useEffect(() => {
    // subscribe to translation changes
    const subscription =
      tolgee.onTranslationChange.subscribe((data) => {
        if (data.key === keyName) {
          setTranslate(tolgee.instant(keyName, parameters));
        }
      });

    return () => {
      subscription.unsubscribe();
    };
  }, [keyName, parameters]);

  return translated;
};

Tolgee instance holds internal cache with all current translations. So when we call tolgee.instant(), we'll get current translation of the key with applied parameters, also we can subscribe to translation changes, which happen e.g. when language is changed or when user manually changes the translation through in-context localization tool.

Imperative translating in React

To create simple to use t function in React, we need to somehow "hook" it to component lifecycle as we need not just to translate keys, but also subscribe the component to translation changes. Simplest solution (as I might given you a hint) is to create hook, which returns this t function. Then we have separate t function for each component and we can connect it to the component lifecycle. Let's look how that can look like.

export const useTranslate: () => ReturnFnType = () => {
  const {tolgee} = useTolgeeContext();

  // dummy state to force component to re-render
  const [_, setDummyValue] = useState(0);
  const reRender = () => {
    setDummyValue((v) => v + 1);
  };

  // array of used keys
  const usedKeysRef = useRef(new Set());

  useEffect(() => {
    const subscription = tolgee.onTranslationChange.subscribe((data) => {
      // check if we are using this key
      if (usedKeysRef.current.has(data.key)) {
        reRender()
      }
    });

    return () => subscription.unsubscribe();
  }, []);

  return (keyName, parameters) => {
    // remember that this key was used
    usedKeysRef.current.add(keyName)

    return tolgee.instant(keyName, parameters)
  };
};

React doesn't have a direct way how to force component to re-render, so we do it through dummy state update.

This hook can be then used in following way:

export const MyComponent = () => {
  const t = useTranslate()

  return <div title={t('title_key')}>...</div>
}

We basically give user a function and then observe what keys is he using it for. When translation changes, we check if it was used before in this component and eventually we force component to re-render.

Notes

Implementation for all frameworks and is quite simplified in order to fit into one article. The core library is in reality a bit more complex, also we've completely skipped in-context localization event handlers (that allows user to click on translation), as it is quite complicated subject.

Implementation for Vue.js

Vue.js has also concept of providing a context to it's children. We can do this by provide method on any component.

export const TolgeeProvider = {
  name: 'TolgeeProvider',
  props: {
    config: {type: Object, required: true},
  },
  created() {
    const tolgee = new Tolgee({...this.$props.config});
    this.tolgeeContext.tolgee = tolgee;
    tolgee.run()
  },
  data() {
    return {
      tolgeeContext: {
        tolgee: null,
        // more reactive properties here
      },
    };
  },
  provide() {
    return {
      tolgeeContext: this.tolgeeContext,
    };
  },
  beforeUnmount() {
    this.tolgeeContext.tolgee.stop();
  },
  render() {
    this.$slots.default()
  },
};

Vue is using methods to manage lifecycle of the component, it is quite similar to React class components. Where Vue is quite different is that it's using reactive objects - everyting you put inside data property, will get turned into reactive objects (which are watching for changes), so that way Vue triggers re-renedering. In example above, we are putting a whole tolgeeContext into data property because in reality we need more things to be passed down and it needs to be reactive.

Now let's look how T component can work.

export const T = {
  name: 'T',
  inject: ['tolgeeContext'],
  props: {
    keyName: {type: String, required: true},
    parameters: Object,
  },
  data() {
    const tolgeeContext = this.tolgeeContext;
    return {
      translation:
        tolgeeContext.tolgee.instant(
          this.$props.keyName,
          this.$props.parameters
        )
    };
  },
  methods: {
    translate(data) {
      if (data.key === this.$props.keyName) {
        this.$data.translation =
          tolgeeContext.tolgee.instant(
            this.$props.keyName,
            this.$props.parameters
          )
      }
    }
  },
  created() {
    const tolgeeContext = this.tolgeeContext;
    this.$options.subscription =
      tolgeeContext.tolgee.onTranslationChange.subscribe(this.translate);
  },
  beforeUnmount() {
    this.$options.subscription.unsubscribe();
  },
  render() {
    return this.$data.translation
  },
};

Similarly as in React, we use tolgeeContext through inject property and subscribe to
translation changes in lifecycle methods.

Imperative translating in Vue

As we don't have anything like hooks in Vue, we'll have to use it's Mixin api. Mixin is a way how to share logic between components while using it's lifecycle methods.

export const TolgeeMixin = {
  inject: ['tolgeeContext'],
  beforeCreate() {
    this.$options.usedKeys = new Set()
  },
  created() {
    const tolgeeContext = this.tolgeeContext;
    this.$options.subscription =
      tolgeeContext.tolgee.onTranslationChange.subscribe((data) => {
        if (this.$options.usedKeys.has(data.key)) {
          this.$forceUpdate();
        }
      });
  },
  methods: {
    $t(keyName, params) {
      this.$options.usedKeys.add(keyName)
      const tolgeeContext = this.tolgeeContext;
      return tolgeeContext.tolgee.instant(keyName, params);
    },
  },
  beforeUnmount() {
    this.$options.subscription.unsubscribe();
  },
};

Mixin can then be used following way:

<template>
  <div :title="$t('title_key')">...</div>
</template>

<script>
export const Component = {
  mixins: [TolgeeMixin],
};
</script>

So here we inject tolgeeContext, subscribe into translation changes and add $t method, which can then be used by the user. We also maintain a list of keys, which were used and we update the component when they change. Notice that Vue has explicit method $forceUpdate, which causes re-render of the component.

Implementation in Svelte

Svelte and Angular sections are written by Jan Cizmar, as he is the author of the integrations

In Svelte we implemented the provider quite similarly as in Vue and React.

<!-- TolgeeProvider.svelte -->
<script>
  import { onDestroy, onMount, setContext } from "svelte";

  export let config: TolgeeConfig;
  const tolgee = new Tolgee(config);

  setContext("tolgeeContext", { tolgee });

  onMount(() => tolgee.run());
  onDestroy(() => tolgee.stop());
</script>

<slot />

The T component that uses the context looks like this:

<script>
  import { onDestroy, getContext } from "svelte";

  export let keyName;
  export let parameters;
  const tolgeeContext = getContext('tolgeeContext');

  let translated
  const translate = () => {
    translated = tolgeeContext.tolgee.instant(
      keyName,
      parameters,
    );
  }

  translate();
  const subscription =
    tolgeeContext.tolgee.onTranslationChange.subscribe((data) => {
      if (data.key === keyName) {
        translate()
      }
    });

  onDestroy(() => {
    subscription.unsubscribe();
  });
</script>

{translated}

The TolgeeProvider and T component are very similar to React implementation.

The differences are:

Svelte has lifecycle methods, React has hooks
Context API has is a bit different

Imperative translating in Svelte

The biggest difference from React integration is in the getTranslate method, which in Svelte returns a Store containing the method to actually translate the key.

import {onDestroy, getContext} from 'svelte';
import {derived, writable} from 'svelte/store';

export const getTranslate = () => {
  const context = getContext('tolgeeContext');
  const tolgee = context.tolgee;

  // set of used keys
  const usedKeys = new Set();

  // dummy store which is updated to forces providing of new translate method
  const updateStore = writable(0);
  const update = () => updateStore.update((number) => number + 1);

  const translate = (keyName, params) => {
    usedKeys.add(keyName);
    return tolgee.instant(keyName, params);
  };

  const subscription =
    tolgee.onTranslationChange.subscribe((data) => {
      if (usedKeys.has(data.key)) {
        update();
      }
    });

  onDestroy(() => {
    subscription.unsubscribe();
  });

  // return new translate method when something is changed
  return derived(
    // when updateStore changes, translate function gets changed as well
    updateStore,
    () => (keyName, params) => {
      return translate(keyName, params);
    }
  );
};

Example usage of getTranslate function:

<script>
  const t = getTranslate();
</script>

<div title={$t('title_key')}>...</div>

In React the useTranslate is hook, which is basically modifying state to force rerender when translation changes and the returned t function called by the new render then returns new value.

Similar thing happens in Svelte, but there the t is actually a Store containing the translating function. That's why there is the $ before the function call. It means that the value should be re-rendered whenever the Store is updated.

Implementation in Angular

The most different approach is used in Angular integration. Angular has no concept of provider, instead we can use module, which setups the Tolgee Core library and provides the service, pipe and component to allow translating in the module components.

The NgxTolgeeModule

@NgModule({
  declarations: [TranslatePipe, STranslatePipe, TComponent],
  exports: [TranslatePipe, STranslatePipe, TComponent],
  providers: [],
})
export class NgxTolgeeModule {
  // @dynamic
  static forRoot(options: TolgeeConfig): ModuleWithProviders<NgxTolgeeModule> {
    options = {filesUrlPrefix: '/assets/i18n/', ...options};
    return {
      ngModule: NgxTolgeeModule,
      providers: [
        TranslateService,
        TranslationsProvider,
        {
          provide: APP_INITIALIZER,
          useFactory: (provider: TranslationsProvider) => {
            return async () => await provider.load(options);
          },
          deps: [TranslationsProvider, TranslateService],
          multi: true,
        },
        {provide: TolgeeConfig, useValue: options},
      ],
    };
  }
}

Cool thing about this is the factory, which enables us to wait for translations to be loaded before it renders the application to the DOM. In other frameworks, this is handled by loadingFallback props or slots, which are rendered when translations are loading.

The translation service and Observables

In Angular world RxJs and its Observable interface are very popular. The Observable is similar thing as an event
emitter. It enables us to emmit new values until we are done and enables us to unsubscribe when we need so. This is
exactly what we need for our purpose.

import {EventEmitter, Injectable, OnDestroy} from '@angular/core';
import {Observable} from 'rxjs';
import {Tolgee, TranslationData} from '@tolgee/core';
import {TolgeeConfig} from './tolgeeConfig';

@Injectable()
export class TranslateService implements OnDestroy {
  constructor(private config: TolgeeConfig) {
  }

  // Logic creating the Instance of Tolgee and lot of other stuff is ommited
  // ...

  private _tolgee: Tolgee;

  public get tolgee(): Tolgee {
    return this._tolgee;
  }

  public translate(
    key: string,
    params = {},
  ): Observable<string> {
    return new Observable((subscriber) => {
      const translate = () => {
        const translated = this.tolgee.instant(
          key,
          params,
        );
        subscriber.next(translated);
      };

      translate();

      const onTranslationChangeSubscription =
        this.tolgee.onTranslationChange.subscribe((data) => {
          if (data.key === key) {
            translate();
          }
        });

      return () => {
        onTranslationChangeSubscription.unsubscribe();
      };
    });
  }
}

The service's translate method creates new Observable and emits new value every time translation is changed, which is emitted by Tolgee instance from @tolgee/core library. It also returns function, which enables us to unsubscribe.

The component with `t` attribute selector

As an equivalent to T component in React, we can use t selector, it subscribes to translate Observable and changes the result according to the new value.

import {Component, ElementRef, Input, OnDestroy, OnInit} from '@angular/core';
import {Subscription} from 'rxjs';
import {TranslateService} from './translate.service';
import {TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE} from '@tolgee/core';

@Component({
  selector: '[t]',
  template: ``,
})
export class TComponent implements OnInit, OnDestroy {
  @Input() params?: Record<string, any>;
  @Input() key: string;
  subscription: Subscription;

  constructor(
    private ref: ElementRef,
    private translateService: TranslateService
  ) {
  }

  ngOnInit(): void {
    const element = this.ref.nativeElement as HTMLElement;
    element.setAttribute(TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE, this.key);

    this.subscription = this.translateService
      .translate(this.key, this.params, this.default)
      .subscribe((translated) => {
        return (element.textContent = translated);
      });
  }

  ngOnDestroy(): void {
    this.subscription.unsubscribe();
  }
}

The `translate` pipe

Pipe is a feature, which is missing in all the other integrations. It's basically function, which is able to change value used in template to some other value.

import {OnDestroy, Pipe, PipeTransform} from '@angular/core';
import {TranslateService} from './translate.service';
import {Subscription} from 'rxjs';

@Pipe({
  name: 'translate',
  pure: false,
})
export class TranslatePipe implements PipeTransform, OnDestroy {
  value = '';
  key: string;
  params: Record<string, any>;
  private subscription: Subscription;

  constructor(protected translateService: TranslateService) {
  }

  ngOnDestroy(): void {
    this.unsubscribe();
  }

  transform(
    key: any,
    params?: Record<string, any>
  ): string {
    if (
      this.key === key &&
      JSON.stringify(this.params) === JSON.stringify(params)
    ) {
      // parameters unchanged
      return this.value;
    }

    this.key = key;
    this.params = params;

    this.unsubscribe();
    this.subscription = this.translate(key, params);

    return this.value;
  }

  private unsubscribe() {
    this.subscription.unsubscribe();
  }

  private translate(key, params) {
    this.translateService.translate(key, params).subscribe((r) => {
      this.value = r;
    });
  }
}

Angular is basically running the transform method every time the user moves mouse or hits some keys, since it is impure pipe, which may return different result for the same input. That happens when language is changed: same key and params, different result.

In comparison to other frameworks it seems that Angular library needs a bit more code and the integration is more complicated.

Conclusion

It is interesting, how these frameworks/libraries take inspiration from each other. Svelte being the newest has something from everyone and the code seems very natural and clean. Vue takes inspiration from both Angular and React and is kinda compromise between them. Then you have React, which stands out with hooks and JSX. And Angular taking inspiration from "classic" Model-View-Controller schema, which is familiar to backend developers.

We'll be glad if you let us know how to improve/simplify an implementation in any of these frameworks/libraries. We don't claim that we know all these frameworks that well. I've used Vue seriously for the first time and Jan was learning Svelte from scratch, while he was implementing this (their documentation is outstanding).

PS: Check Tolgee.io and give us github stars

Faster! Optimizing React app to the bone

Štěpán Granát — Thu, 25 Nov 2021 06:54:55 +0000

In Tolgee platform, we manage translations. So our most important view is a list of translations, every row contains key and related translations in different languages. As this view serves multiple purposes, we have quite a lot of requirements and fulfilling all of them required quite a bit of optimizations, which I'd like to share with you today.

What are we dealing with

Mainly, a whole view is using infinite scrolling, where we automatically fetch additional data when user scrolls down. Every row needs to have some buttons, so he can edit, select or modify state of translations. We have search and filters, which should work swiftly when applied. Then we have resible columns, which allow user to change whole layout by mouse dragging. We also need to detect overflowing text vertically, which can't be done simply through css, but we need to "test render" it first and then see if it fits. And last but not least (as new features will surely come in the future), everything need to work with focus, so user can controll it through keyboard.

How to identify problems generally

Basically always when your React application is slow it's due to too many components re-rendering or too often. React have very useful Developer Tools, where you can profile your App and then find out which components are taking most of the time to render.

When I identified slow components, I needed to understand why exactly is rendering so slow.
One might think that if we keep our components small, the amount of rendering should be managable, but as it turned out this was not the case. Main problem is that components often depend on one another (like parent and child or using same data) and when small change in your state causes a big chunk of your app to re-render, you might have to apply additional optimizations, which React doesn't make automatically.

To make sure that my optimizations are actually working I've brought my super old laptop to work, which I've considered the most reliable benchmark of improvement

One problem at a time

I will now try to ilustrate different situations on the example of our app and offer a way which we choosed as a solution. It is important to understand what exactly is happening, because optimizations are often tradeoffs - you exchange comfort (elegance/convenience/generality) for speed. So if you do incorrect optimizations, you might improve nothing and only ruin your code.

Optimizing state management

When we simply use Context API for our main state, we end up re-rendering almost entire view on every change. This issue is mostly visible when we use search field, as typing will become unbearably slow.

You can solve this by using some state management tool (e.g. Redux, MobX, ...), or you can use context in a clever way, so you minimize re-rendering (check my previous article).

Large number of children re-render

Clever state management still won't protect us completely against unnecessary re-renders. In some cases the fact the Component update causes all children re-render can be too expensive. You can avoid this by wrapping each child with React.memo - React will then render child only when props change. However, make sure that you fully understand how it works in the docs, and then check that it really helped.

In our case we wrap each row in the list with React.memo. Because the row is relying mostly on fetched data, we can save quite a lot of unnecessary re-rendering.

Infinite scolling

Our main problem now is that our page can have bascially infinite number of components. A way to solve this is to only render elements, that are currently visible to the user. It's better to use some third party solution for this, because it's quite complicated to do right. After some trial and error we ended up with library react-list.

Libraries like these usually require you to specify size of the components upfront (as they need to calculate a full length of the scrollable area without actually rendering the content), which can be quite problematic - in our case row sizes are variable and so we can't really tell how big it will be untill we render it. react-list is able to solve this by only asking you to estimate the size of rows and then when it actually renders the element, it updates the size automatically. This can lead to your scrollbar jumping (as a height of the container is changing while you are scrolling in it), but if your estimation is somehow decent, it is pretty minor issue.

Nice! So now we decreased an overall number of components displayed from infinity to "it depends on your screen size". However we have another problem ...

Reducing rows complexity

Our infinite scrolling optimization wasn't without tradeoff. It takes siginificant time to render each row and because user can scroll quite fast, it can lead to content not keeping up with scrolling. Problem that is related to this is our resizeble layout which is also very slow.

This is quite difficult problem, because only thing that you can do here is to reduce complexity of individual rows. In our case we've mostly solved it by clever usage of css grid, which allowed us create complex layouts using only few html elements.

Another thing was to prevent displaying unnecessary stuff on first render. All our buttons are hidden by default and only appear when you hover the given row. We were doing this only by css, which doesn't help React at all. So my solution was to hide the buttons for real (not render them) and show them only onmouseover, which improved situation quite significantly.

This solution brought a new problem, that you were not able to use focus with tab, as buttons were not actually present. I've solved this by always rendering first and last button (but hiding them with css) and other buttons would render when focus is within the row itself or when mouseover - this way user won't recognize the difference.

Conclusion

I was quite scared when I realized that our Application is becoming very slow and at the end I've spend one full week with these optimizations, but after some trial and error I've understood weak points and was able to target them. Considering the complexity it works fine even on my super old university laptop and I've learned a lot.

I'm now happy developer and I spend quite a lot of my working time just scrolling around in our App.

PS: Check Tolgee.io and give us github stars

React doesn't need state management tool, I said

Štěpán Granát — Mon, 08 Nov 2021 08:50:53 +0000

From time to time someone still tells me that is using REDUX or similar tool in their project. I usually respond, that I wouldn't use it as now with hooks and context API you don't need it.

But context API usually brings performance problems and is also a bit awkward to use it properly, so today I'll try to show how to avoid common problems, and also build your own (micro) state management tool, without any compromises.

Naive solution

Basic idea is to manage state in one component and pass the whole it by context so it's accessible from all child components, so we can avoid props drilling.



export const StateContext = createContext(null);
const Provider = () => {
  return (
    <StateContext.Provider value={state}>
      <ChildComponent />
    </StateContext.Provider>
  )
}

Using dispatch

However you also need some way how to modify the state from children, you could pass individual functions to the context, but I personally don't like that as the state will get complex very fast. I like idea of dispatching events (similarly as in REDUX), so we basically pass one function which you can use to dispatch all different actions that you need. We could pass it through the same context as the state, but I don't like mixing it with the state, so I pass it through a separate context.



const StateContext = createContext(null);
const DispatchContext = createContext(null);

export const Provider = () => {
  const [state, setState] = useState(...)

  const dispatch = (action) => {
    switch (action.type) {
      case 'CHANGE_STATE':
        setState(action.payload)
        break;
      ...
    }
  }

  return (
    <StateContext.Provider value={{state, ...}}>
      <DispatchContext.Provider value={dispatch}>
        <ChildComponent />
      </DispatchContext.Provider>
    </StateContext.Provider>
  )
}

I also like creating hook for getting the dispatch function to make it more explicit:



export const useDispatch = () => {
  return useContext(DispatchContext)
}

Basically we are separating data from actions - provider component provides data to children. Children can dispatch actions to modify the data, but it's controlled by provider component, so it has control over it. Dispatched actions can be understood similarly as e.g. dom events, except we know who will receive it.

Now let's look at the performance side as if we want to use this as a replacement of REDUX, it needs to be able to handle big states with a lot of components subscribed.

Avoiding unnecessary children re-creation

In this configuration we are really inefficient, as all the children will get re-rendered every time we change something in the state. This happens because every time we update state in Provider component, all it's children will get re-created. We could use React.memo on children to avoid this, however nicer solution is to pass children from component above, so when the Provider is updated, children will stay the same. And we only update actual context consumers.



export const Provider = ({ children }) => {

  ...

  return (
    <StateContext.Provider value={{state, ...}}>
      <DispatchContext.Provider value={dispatch}>
        {children}
      </DispatchContext.Provider>
    </StateContext.Provider>
  )
}

In parent we do:



export const Parent = ({ children }) => {
  return (
    <Provider>
      <ChildComponent />
    </Provider>
  )
}

Now the provider component is managing the context, but is not managing children (only passing them). It took me a while to understand this subtle difference as it is quite small change in the code, with big consequences.

The trick is to understand, that when we put <ChildComponent >, we are basically creating new React.Node every time, so all the children are re-rendered, unless we wrap them in React.memo.

So with this change, we update only components which are using the context.

Avoiding dispatch causing re-renders

Currently dispatch function is re-created every time the state is changed, which mean that all components using it will get re-rended, even though they are not using StateContext. Usually if we want to have stable function react documentation advices to use useCallback, but in this case it will help us only partially, because, that will basically cause "caching" of dispatch function and we wouldn't be able to use outer scope variables without including them into dependencies - and then the dispatch function would still get recreated when dependencies change. We will need to use ref to help us with this.



...

export const Provider = ({ children }) => {
  const [state, setState] = useState(...)

  const dispatchRef = useRef()

  // new function with every render
  const dispatchRef.current = (action) => {
    switch (action.type) {
      case 'CHANGE_STATE':
        // we can use outer scope without restrictions
        setState({...action.payload, ...state})
        break;
      ...
    }
  }

  // stable dispatch function
  const dispatch = useCallback(
    (action: ActionType) => dispatchRef.current(action),
    [dispatchRef]
  );

  return (
    <StateContext.Provider value={{state, ...}}>
      <DispatchContext.Provider value={dispatch}>
        {children}
      </DispatchContext.Provider>
    </StateContext.Provider>
  )
}

This way stable dispatch function is passed to the DispatchContext and we can use outer scope without limitations.

Subscribable context

Last optimization we'll need is ability of the component subscribe only to part of the state. Now components can only use whole state and even when they need just small piece (e.g. one boolean value), they'll get notified every we change the state. This is not the best practice as we would still get unnecessary re-renders. The way to solve this is through use-context-selector.

This library is quite simple and it allows to use selector function, to "pick" what we want from the state.



import { createContext } from 'use-context-selector';

const StateContext = createContext(null);

export const Provider = ({ children }) => {
  return (
    <StateContext.Provider value={{state, ...}}>
      <DispatchContext.Provider value={dispatch}>
        {children}
      </DispatchContext.Provider>
    </StateContext.Provider>
  )
}



import { useContextSelector } from 'use-context-selector';

export const Subscriber = () => {
  const somePart = useContextSelector(StateContext, context => context.somePart)
}

Oh, wait that is cheating! You said you will only use Context API!

This library is quite simple wrapper of React.Context api. It uses ref to wrap passed value, so that components are not re-rendering automatically and then it keeps list of subscribers. When value changes it runs all the subscribed functions and if the value from the selector is different than before it forces the subscribed Component to re-render. Similar concept is used e.g. in redux useSelector hook. So I say, it's quite standard solution and why build a new one, when it already exists?

PS: there is even a open RFC to add something like this directly into react

Final product

We can wrap this whole functionality to be reusable (+ add typescript types)



import React, { useCallback, useRef } from 'react';
import { createContext, useContextSelector } from 'use-context-selector';

type DispatchType<ActionType, DispatchReturn> = (
  action: ActionType
) => DispatchReturn;

type SelectorType<StateType> = (state: StateType) => any;

export const createProvider = <
  StateType,
  ActionType,
  DispatchReturn,
  ProviderProps
>(
  body: (
    props: ProviderProps
  ) => [state: StateType, dispatch: DispatchType<ActionType, DispatchReturn>]
) => {
  const StateContext = createContext<StateType>(null as any);
  const DispatchContext = React.createContext<
    DispatchType<ActionType, DispatchReturn>
  >(null as any);

  const Provider: React.FC<ProviderProps> = ({ children, ...props }) => {
    const [state, _dispatch] = body(props as any);
    const dispatchRef = useRef(_dispatch);

    dispatchRef.current = _dispatch;

    // stable dispatch function
    const dispatch = useCallback(
      (action: ActionType) => dispatchRef.current?.(action),
      [dispatchRef]
    );

    return (
      <StateContext.Provider value={state}>
        <DispatchContext.Provider value={dispatch}>
          {children}
        </DispatchContext.Provider>
      </StateContext.Provider>
    );
  };

  const useDispatch = () => React.useContext(DispatchContext);
  const useStateContext = (selector: SelectorType<StateType>) =>
    useContextSelector(StateContext, selector);

  return [Provider, useDispatch, useStateContext] as const;
};

Usage example



type ActionType =
  | { type: 'CHANGE_STATE'; payload: ... }
  ...

export const [
  TranslationsContextProvider,
  useTranslationsDispatch,
  useTranslationsSelector,
] = createProvider(
  (props /* provider props */) => {
    const [state1, setState1] = useState(...)
    const [state2, setState2] = useState(...)
    const {data, isLoading} = useQuery(...)

    const dispatch = (action: ActionType) => {
      switch (action.type) {
        case 'CHANGE_STATE':
          setState(action.payload)
          break;
        ...
      }
    }

    const state = {
      state1,
      state2,
      data,
      isLoading
    }

    // don't forget to return state and dispatch function
    return [state, dispatch]
  })

Lets summarize advantages of this solution:

Simple usage, nothing new to learn no boilerplate as with REDUX etc.
More efficient than Context api used naively
It scales as you have the whole power of hooks
You can use many instances and scope them only to the part of app that need them

In Tolgee.io, we use this on our most complicated view, where we handle translations table and we didn't have any problems with it yet.

What do you think?

PS: Check Tolgee.io and give us github stars

DEV Community: Štěpán Granát

How to remove Java from JavaScript

Wait, what's wrong with the classes?

Like a fish out of water

State and lifecycle

Classes without classes

Closure objects

How about inheritance?

Seems good. What's the catch?

Conventions

Conclusion

Is Turborepo overhyped?

What is Turborepo and why do we need it?

Setting up

Where the real issues started

Maybe I made a mistake

Or not?

My conclusion

Taking localization to i18next level

Why i18next?

Additional tools for i18next

How to integrate with Tolgee

How it works?

I want to try this!

Using invisible text for better localization

Background

Why is context important?

Text based solution

The idea of invisible marks

How do we make text invisible?

Can I try this?

Conclusion

Same logic in 4 major FE frameworks, how do they compare?

Overall design

General integration library architecture

Translating regular texts

Translating imperatively

Source of data

Implementation for React

Imperative translating in React

Notes

Implementation for Vue.js

Imperative translating in Vue

Implementation in Svelte

Imperative translating in Svelte

Implementation in Angular

The NgxTolgeeModule

The translation service and Observables

The component with t attribute selector

The translate pipe

Conclusion

Faster! Optimizing React app to the bone

What are we dealing with

How to identify problems generally

One problem at a time

Optimizing state management

Large number of children re-render

Infinite scolling

Reducing rows complexity

Conclusion

React doesn't need state management tool, I said

Naive solution

Using dispatch

Avoiding unnecessary children re-creation

Avoiding dispatch causing re-renders

Subscribable context

Final product

The component with `t` attribute selector

The `translate` pipe