The complete guide to connect Akeneo PIM to your online translation solution

#How to build your connector?

#A connection compliant method

Now that you have a good overview of Akeneo PIM data, you are probably wondering how your online translation connector will interact with Julia while being compatible with all of our PIM editions.

The best way to do this is to develop a "connection-compliant" connector based on our API.

Translation connector overview

Please don't hesitate to read our "4 reasons why you should use our API" page!

We suggest following our method which leans on some useful existing PIM features to interact with Julia.

This method is based on one of our Marketplace connector specifications: GlobalLink Connect for Akeneo from the Translations.com company.

#Some pre-requisites

First of all, we're going to ask Julia to do some work!
Indeed, in order for your connector to interact with Julia, we will have to ask her to check some pre-requisites and to add some additional data in her PIM.

#Create a dedicated connection

First, in order to communicate with your connector and obtain API credentials, Julia needs to create a dedicated connection for your connector.

To do so she will need to:

  1. Go to the System menu and then, on the Connections submenu
  2. Click on Create
  3. In the Label field, enter the name of your connector.
  4. Choose the Other flow type

Whenever you create a connection, the PIM automatically generates a set of credentials for you.

These API credentials consist of 4 items:

  • the client id,
  • the secret,
  • the connection username,
  • the connection password.

Don't forget to set the permissions of this connection!

As you may understand, your connector needs to have a dedicated UI or a configuration file in order to manage these PIM API credentials.

#Check Julia's PIM data

Then, in order for your connector to be able to add translations, Julia's PIM must be correctly set up.

That's why you must check with Julia that in her PIM:

  • All locales required for translations have been activated.
  • All attributes requiring translation for products or product models are set to "localizable".

#Create a translation attribute group

First, in order not to confuse these new product attributes with some of her other product attributes, it is necessary for Julia to create a specific attribute group named Translations.

To create this attribute group:

  1. Go to Settings > Attribute groups
  2. Click on CREATE in the top-right corner
  3. Add a new attribute group with the code and label: Translations.

#Create translation attributes

Then, Julia must create 6 new attributes in this attribute group:

  • Translation submission name: This attribute allows Julia to set a name for her translation project. It'll also allow her to easily find the project in the interface of your online translation solution. Set up this attribute as followed:
    • Attribute type: text
    • Attribute code: translationName
    • Attribute label: Translation submission name
    • Attribute group: Translations
    • Usable in grid: enabled
  • Translation submitter: This attribute allows Julia to associate her name with her translation project. Among its options, this simple select attribute should list all the possible contributor names. Set up this attribute as followed:
    • Attribute type: simple select
    • Attribute code: translationSubmitter
    • Attribute label: Translation submitter
    • Attribute group: Translations
    • Usable in grid: enabled
  • Translation queued: This attribute allows Julia to define if a product needs to be translated. Set up this attribute as followed:
    • Attribute type: Yes/No (Boolean)
    • Attribute code: translationQueued
    • Attribute label: Translation queued
    • Attribute group: Translations
    • Usable in grid: enabled
  • Translation locales: This attribute allows Julia to choose one or more target locales for her translation project. This multi-select attribute should contain, in its options, all the possible destination locales Julia can use for her translation requests. These same locales must already exist in Akeneo PIM and in your online translation tool. Set up this attribute as followed:
    • Attribute type: multi-select
    • Attribute code: translationLocales
    • Attribute label: Translation locales
    • Attribute group: Translations
    • Usable in grid: enabled
  • Translation due date: This attribute allows Julia to indicate when she would like her products to be translated. Set up this attribute as followed:
    • Attribute type: date
    • Attribute code: translationDate
    • Attribute label: Translation due date
    • Attribute group: Translations
    • Usable in grid: enabled
  • Translation status: This attribute allows your translator to give a status about the translation project to Julia. As this attribute has a Read only property, it can't be modified by Julia. This status can only be modified by your connector through the API and set the translation project status for each desired locale. This attribute contains these options:
    Code Label
    INPROGRESS In progress
    TRANSLATED Translated
    CANCELLED Cancelled
    Then, set up this attribute as followed:
    • Attribute type: simple select
    • Attribute code: translationStatus
    • Attribute label: Translation status
    • Attribute group: Translations
    • Value per locale: enabled (in order to have a status for each locale)
    • Read only: enabled (can only be modified via API)
    • Usable in grid: enabled

To create an attribute:

  1. Go to Settings > Attributes
  2. Click on CREATE ATTRIBUTE in the top-right corner of the screen

This list of attributes is not exhaustive and may need to be adapted depending on your online translation solution and the information required to perform a translation project.

Once the Translation attribute group and its attributes have been created, Julia needs to assign the Translations attribute group to all existing families.

Julia can do this by using this bulk action process:

  1. Go to Settings > Families
  2. Select all families
  3. Click on BULK ACTIONS at the bottom of the page
  4. Select Set attributes requirements and then click on NEXT
  5. Click on ADD BY GROUPS and ADD the Translations attribute group
  6. Click on CONFIRM

And that's it! Congratulations! 🎉
Everything is now ready for Julia to receive the PIM products she wants to translate!

#Julia's translation process

As you have understood, Julia will use the previous PIM attributes to define which of her products are to be translated and how they will be processed.

Now let's see how Julia will work with these new PIM translation features.

#Select the products to be translated

First, Julia needs to select the product she wants to translate:

  1. Go to Products
  2. Select the "source" locale
  3. Select the products (and/or product models) you want to translate

For a seamless product selection, Julia can use her PIM grid filtering system or create a specific view.

#Perform a "bulk action"

Then, she needs to perform a bulk action on these products.

For this action, Julia has to:

  1. Click on BULK ACTIONS at the bottom of the page
  2. Select Edit attributes values and click on NEXT
  3. In SELECT ATTRIBUTES, search and select these 5 translation attributes and click on ADD:
    • Translation submission name
    • Translation submitter
    • Translation queued
    • Translation locales
    • Translation due date
  4. Now set the translation attributes:
    • Translation name: Enter the desired name for the translation project,
    • Translations submitter: select Julia's name,
    • Translation queued: Select Yes to enable the attribute,
    • Translation locales: select the desired target locales for translation,
    • Translation due date: select the translation deadline.
  5. Click on NEXT and CONFIRM to launch the bulk action.

After this last action, the bulk action will run and Julia will be notified in the Akeneo PIM notification bar once it is successfully executed.

With these new attributes, your connector is now ready to go! Let's see how it'll behave on the other side of the connector.

#How it works with your connector?

Find products with the "translation queued" status enabled

At regular intervals, your connector will need to retrieve products where the Translation queued attribute has been set to enable (set to true).

You can do this by using our PIM API filtering system on product attribute value.

Tell Julia that her translation project is "in progress"

Then, your connector needs to set the "translation queued" attribute to false (To prevent the product from being reprocessed by the connector) and change the Translation status attribute to IN PROGRESS to indicate Julia that the translation is being processed by one of your translators.

Retrieve "text" product attributes

You have 2 possibilities to develop this action:

  • The simplest but less automatic way is that, directly in your connector configuration, Julia and Peter declare the exhaustive list of text attributes to be translated (by product family). Then, your connector has to consult this list one family at a time.
  • The other way is that your connector can analyze the PIM product families to determine which attributes have a "text" type and, therefore, can be translated. It must also check that the attribute is "localizable".

We suggest that you develop the first solution during the first iteration of your connector. If in your projects Julia handles a large number of product families with many attributes to translate, you can then upgrade your connector with the second solution.

Using the "get a list of products" API endpoint (with the correct filter), your connector will retrieve a JSON structure of each localizable products.

Then, with the help of the family code of these products, your connector will be able to call the "get the list of attributes" API endpoint to retrieve each attribute type that composes this product family.

By analyzing these types, you will be able to define for your translator which are the textual attributes they need to translate.

What about simple and multi select attribute types?

We mentioned earlier that it would be interesting for your connector to allow the translation of "simple" or "multi select" type attributes.

To do so, Julia and Peter can declare the exhaustive list of "simple" or "multi select" attributes in your connector configuration, just as they do for "text" attributes.

When Julia requests the translation of a product, your connector will then automatically translate the "options" of the "simple" or "multi select" attributes that have not been translated yet.

To perform this action, your connector can use the "get list of attribute options" API endpoint.

Tell Julia that her translation project is either finished...

When the translation is finished, your translator needs to set the Translation status attribute to TRANSLATED and to send all the translated product data back in the PIM.

...or has been cancelled.

If, for some reason, the translation project has been canceled, your translator needs to set the Translation status attribute to CANCELLED and to send this product data back into the PIM.

To develop these connector actions, and to understand our API, please follow our wonderful dedicated API documentation!

#Check the "Translation status"

Now let's go back to Julia's side and see how she can check her translation project status.

As the Translation status has been declared as Usable in grid, Julia can:

  • Customise her grid to add the Translation status attribute: this will allow her to sort her products according to their translation status.
  • Add the Translation status attribute in her grid filters: this will allow her to filter only products with a specific translation status and create a dedicated view for this feature.

Of course, she can do the same for all the other "Translation" attributes.

As you can see, without any PIM customization and with a few developments on your connector, Julia can build some powerful translation features in her PIM!

#How to start?

Our recommendation: always listen to your customer's needs first!

We are aware that it is difficult and expensive in terms of investment to achieve a 100% complete online translation connector that is flexible enough to adapt to any Julia's project.

Our advice: adopt an Agile approach!

  • Interview your future potential customers about their needs
  • Set priorities based on the most generic needs
  • Develop in successive iterations