How do you define translatable entities?

[skid]

I could not find this in the documentation for adding new entities, but I can see in the Vendure codebase that for each Entity class there is also an EntityTranslation class - so it would be nice to have some explanation on how to use the translation feature.

[michaelbromley]

Yes there are no docs on this, so I'll write a rough guide here and add some docs in future:

(using the Product entity as an example)

1. Any fields that should be translated are given the type LocaleString, and are not decorated with @Column() as they are not actually stored in the DB, but are populated at runtime:

   name: LocaleString;
   
   slug: LocaleString;
   
   description: LocaleString;

2. The entity should implement the Translatable interface, which means it will have a property translations which looks like this :

    @OneToMany(type => ProductTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Product>>;

3. A corresponding <entityName>Translation entity must be defined, which implements the Translation<T> interface. This means it will have a languageCode and base properties, as well as a string field corresponding to each of the LocaleString fields of the base entity:

   @Column('varchar') languageCode: LanguageCode;
   
   @Column() name: string;
   
   @Column() slug: string;
   
   @Column('text') description: string;
   
   @ManyToOne(type => Product, base => base.translations)
   base: Product;

4. The GraphQL type for the entity should have a translations field with an array of translations that look like this:

   type ProductTranslation {
     id: ID!
     createdAt: DateTime!
     updatedAt: DateTime!
     languageCode: LanguageCode!
     name: String!
     slug: String!
     description: String!
   }
   
   type Product implements Node {
     # other fields omitted
     name: String!
     slug: String!
     description: String!
     translations: [ProductTranslation!]!
   }

5. The GraphQL input types for creating/updating should likewise have a translations field which looks like

   input ProductTranslationInput {
     id: ID
     languageCode: LanguageCode!
     name: String
     slug: String
     description: String
   }
   
   input CreateProductInput {
     # other fields omitted
     translations: [ProductTranslationInput!]!
   }

6. When creating an instance of the entity, you use the TranslatableSaver service which will save the entity itself plus create translation entities for each of the translations provided:

   const product = await this.translatableSaver.create({
           ctx,
           input,
           entityType: Product,
           translationType: ProductTranslation,
    });

7. When querying the entity, in order to select the correct translation and populate the LocaleString fields of the base entity, you use the translateDeep() function:

       async findOne(ctx: RequestContext, productId: ID): Promise<Translated<Product> | undefined> {
         const product = await this.connection.findOneInChannel(ctx, Product, productId, ctx.channelId, {
           relations: this.relations,
           where: {
               deletedAt: null,
           },
         });
         if (!product) {
           return;
         }
         return translateDeep(product, ctx.languageCode, ['facetValues', ['facetValues', 'facet']]);
     }

   The translateDeep() function's 3rd argument is an array of relations which are also translatable. It allows the entire nested object of related entities to be translated all at once. If your entity does not have translatable relations, you just leave that as an empty array.

[michaelbromley]

It should be exported in v1.1. If you haven't updated yet, it's fine to do a deep import and then change it to a regular import after updating.

[skid]

One more question: I see in the vendure code there are resolvers for translatable fields - e.g. the ProductEntityResolver has this code in it:

 @ResolveField()
    name(@Ctx() ctx: RequestContext, @Parent() product: Product): Promise<string> {
        return this.localeStringHydrator.hydrateLocaleStringField(ctx, product, 'name');
    }

What does the localStringHydrator do, if translateDeep takes care of the locale transaltions?

[michaelbromley]

This code is to guard against the situation where translateDeep has not been called, which can arise due to the dynamic and nestable nature of GraphQL queries. Since it is impossible for the service layer method to know exactly what nested types will be required from the client, your code needs to make a decision about exactly what relations will be joined & translated. But if the client requests some nested relation that was not hard-coded in your code, then the localestrings will not have been populated and you'll get an error.

So the LocaleStringHydrator can be used to say "if this localestring was already hydrated, great, return it. If not, let's lazily query the translations for this entity and populate the localestring values". It also uses a caching mechanism to make this more efficient and prevent double work.

[skid]

And another one: Is there some kind of a helper / tool / library for constructing translations when extending the Admin UI? It would be useful to see a plugin example where the Admin UI is extended with a translatable entity.

[michaelbromley]

I use https://github.com/biesbjerg/ngx-translate-extract to automatically extract translation tokens from my component templates / TS files. I've not tried setting it up in the context of a plugin UI extension though. Would probably be good to incorporate this into the real-world-vendure repo.