# Proper way to access translations of IFC entities?

**URL:** <https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092>\
**Category:** bSDD\
**Created:** [February 7, 2022, 9:13pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092 "2022-02-07T21:13:35Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![stefkeB](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/stefkeb/32/1755_2.png) [@stefkeB](https://forums.buildingsmart.org/u/stefkeB)\
**Post date:** [February 7, 2022, 9:13pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/1 "2022-02-07T21:13:35Z")

</div>

When you browse the HTML version of the IFC documentation, you get access to the explanations and translations.

[https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2\_TC1/HTML/link/ifcairterminal.htm](https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/ifcairterminal.htm)

However, the **XSD** or **Express** schemes only contain the main English entities and attributes. **Propertysets** are in external XML files and the translation terms are… somewhere else?

I understand that the documentation is generated from **IfcDoc** which is used to organise the schema and edit the descriptions. I was under the impression that the bSDD would help us to access terms and their translations. But I cannot retrieve them anymore.

Is there support for translations of terms in the current version of bSDD?

[https://search.bsdd.buildingsmart.org](https://search.bsdd.buildingsmart.org)

---

<div class="post-metadata">

**Author:** ![daviddelven](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/daviddelven/32/2384_2.png) [@daviddelven](https://forums.buildingsmart.org/u/daviddelven)\
**Post date:** [February 9, 2022, 3:42pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/3 "2022-02-09T15:42:14Z")

</div>

Yes, @stefkeB . It is an ongoing project within the bSI regarding entity translation in several languages using an efficient digitally-based method. Our chapter is also collaborating with it. I suggest you ask @jwouellette and maybe he can provide you update info about its current progress.

---

<div class="post-metadata">

**Author:** ![berlotti](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/berlotti/32/557_2.png) [@berlotti](https://forums.buildingsmart.org/u/berlotti)\
**Post date:** [February 9, 2022, 4:13pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/4 "2022-02-09T16:13:59Z")

</div>

The official translations are developed and maintained on [https://translations.buildingsmart.org/](https://translations.buildingsmart.org/)

Publication of approved translations are published on GitHub, in bSDD and through an API.

Translations can be provided by everyone (feel free to help!).  
Chapters are organising proofreading.

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 1, 2023, 1:59pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/5 "2023-04-01T13:59:44Z")

</div>

@berlotti , @artur_tomczak

Where and how are the translations deployed?

- [IfcAirTerminal (bSDD)](https://search.bsdd.buildingsmart.org/Classification/Index/71017) shows only “English” in the “Select language” box.
- Our investigation of JSON, RDF and GraphQL (see [Semantic bSDD](https://bsdd.ontotext.com/README.html#improve-multilingual-support) sec `improve-multilingual-support`) shows that there are no fields that can carry multilingual names/definitions.
- Our GraphQL platform (Semantic Objects) has various capabilities for selecting by lang tag, and for lang fallback (eg the list `de,en-GB,en,~` means “first give me `de`; if not available then `en-GB`, else any `en` variant, finally any lang at all”) . See [GraphQL Query Tutorial — Semantic Objects 4.0.0 documentation](https://platform.ontotext.com/semantic-objects/tutorials/graphql-query.html#filtering-literal-values) sec `filtering-literal-values`

cc @Nata_Ke

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 5, 2023, 11:12am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/6 "2023-04-05T11:12:31Z")

</div>

There are no translations of IFC approved as of now, that’s why you don’t see them in bSDD. But the intention is to have them in bSDD as soon as they are approved.

You can check other classifications that have translations, such as our demo “Fruits and Vegetables”. Check apple for example: [Apple (bSDD)](https://search-test.bsdd.buildingsmart.org/Classification/Index/97762)

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 5, 2023, 11:25am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/8 "2023-04-05T11:25:14Z")

</div>

But is the multilingual data returned by the APIs?  
If I try this, it returns English, same as if `Accept-Language` is not specified:

`curl -L -HAccept-Language:pl https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple|jq .`

Are there fields in GraphQL, JSON and RDF to accommodate multilingual strings?

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 5, 2023, 11:50am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/9 "2023-04-05T11:50:22Z")

</div>

you make separate requests for each language, for example to access the Polish version of the apple class, you could use:

> [https://test.bsdd.buildingsmart.org/api/Classification/v4?namespaceUri=https%3A%2F%2Fidentifier.buildingsmart.org%2Furi%2Fbs-agri%2Ffruitvegs-1.0%2Fclass%2Fapple&languageCode=pl-PL](https://test.bsdd.buildingsmart.org/api/Classification/v4?namespaceUri=https%3A%2F%2Fidentifier.buildingsmart.org%2Furi%2Fbs-agri%2Ffruitvegs-1.0%2Fclass%2Fapple&languageCode=pl-PL)

similar to how the web page only shows you one language at a time.

Edit: that was for REST-JSON. You could also ask for TTL using Curl:

> curl -X ‘GET’   
> ‘[https://test.bsdd.buildingsmart.org/api/Classification/v4?namespaceUri=https%3A%2F%2Fidentifier.buildingsmart.org%2Furi%2Fbs-agri%2Ffruitvegs-1.0%2Fclass%2Fapple&languageCode=pl-PL](https://test.bsdd.buildingsmart.org/api/Classification/v4?namespaceUri=https%3A%2F%2Fidentifier.buildingsmart.org%2Furi%2Fbs-agri%2Ffruitvegs-1.0%2Fclass%2Fapple&languageCode=pl-PL)’   
> -H ‘accept: text/turtle’

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 5, 2023, 11:55am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/10 "2023-04-05T11:55:13Z")

</div>

- Not yet available on GraphQL, and the JSON and RDF entity APIs (i.e. resolving the semantic URL)?
- Which of the following fields are in which record? Eg is `dataType` repeated between the EN and PL records, or recorded only once? Does `description` come from the EN record as fallback, or is it repeated in the PL record?

```auto
name: "Objętość",
description: "The volume of an apple",
dataType: "Real",
dimension: "3 0 0 0 0 0 0",

```

- The strings in JSON don’t indicate their language. Eg `"Objętość"@pl, "The volume of an apple"@en`
- The strings in RDF indicate a language but assume it’s the same for the whole record, which is not true: `bsdd:Name "Objętość"@pl-pl; bsdd:PhysicalQuantity "Volume"@pl-pl`
- (Technically speaking, `@pl-pl` is better written `@pl` since in Poland they don’t speak any special dialect of Polish)

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 5, 2023, 12:10pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/11 "2023-04-05T12:10:56Z")

</div>

> [@VladimirAlexiev](#):
>
> (Technically speaking, `@pl-pl` is better written `@pl` since in Poland they don’t speak any special dialect of Polish)

Please refer to the list we have available here: [https://api.bsdd.buildingsmart.org/api/Language/v1](https://api.bsdd.buildingsmart.org/api/Language/v1)

> [@VladimirAlexiev](#):
>
> The strings in JSON don’t indicate their language. Eg `"Objętość"@pl, "The volume of an apple"@en`

One part is the data model, another is how authors define their content. In that case, the description was uploaded as Polish but was not translated properly. (It was my fault 😉 )

> [@VladimirAlexiev](#):
>
> Not yet available on GraphQL, and the JSON and RDF entity APIs (i.e. resolving the semantic URL)?

What do you mean? It is possible with REST-JSON and REST-TTL (RDF) APIs. Not sure about GraphQL, can you help @Erik.bSDD?

> [@VladimirAlexiev](#):
>
> Which of the following fields are in which record? Eg is `dataType` repeated between the EN and PL records, or recorded only once? Does `description` come from the EN record as fallback, or is it repeated in the PL record?

Check our documentation to see which attributes can be translated (marked in “Translatable?” column): [https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20JSON%20import%20model.md](https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20JSON%20import%20model.md). The rest of the content is taken from the initial upload.

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 5, 2023, 12:20pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/12 "2023-04-05T12:20:58Z")

</div>

> `@pl-pl` is better written `@pl`

`en-GB` is ok, `pl-PL` is nok

> In that case, the description was uploaded as Polish but was not translated properly.

You assume EVERYTHING will be translated uniformly. From my experience with large thesauri, I think that assumption is unrealistic, so you need to think about “language fallback” (see link above) and strings in the payload should indicate their language (be self-describing).

> It is possible with REST-JSON and REST-TTL

I mean what’s called “entity API”, i.e. following TimBL’s basic web principles (URLs should resolve, and return useful data). Can you get Polish from the semantic URL [https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple](https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple)? Using standard content negotiation (Language and MIME type)?

> The rest of the content is taken from the initial upload.

Does that mean duplicated? So instead of multilingual entities (eg Domains, Classifications), you have independent entities, where one has been translated from the other?

To give a turtle example:

```ttl
# THIS IS GOOD
<https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple> a :Classification;
  :name "Apple"@, "Jabłko"@pl;
  :dataType: "Real",
  :dimension: "3 0 0 0 0 0 0".

# THIS IS BAD
<https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple/en> a :Classification;
  :name "Apple"@;
  :dataType: "Real",
  :dimension: "3 0 0 0 0 0 0".
<https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple/pl> a :Classification;
  :name "Jabłko"@pl;
  :dataType: "Real",
  :dimension: "3 0 0 0 0 0 0".

```

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 5, 2023, 1:01pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/13 "2023-04-05T13:01:40Z")

</div>

For some of the questions there is an answer in how the bSDD stores the data and what is the input data structure: [https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20JSON%20import%20model.md](https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20JSON%20import%20model.md)  
But good improvement suggestions are welcome and I will go through your list in due time!

> [@VladimirAlexiev](#):
>
> `en-GB` is ok, `pl-PL` is nok

those are standard country-language codes from ISO, can you explain what is the problem with them?

> [@VladimirAlexiev](#):
>
> I mean what’s called “entity API”, i.e. following TimBL’s basic web principles (URLs should resolve, and return useful data). Can you get Polish from the semantic URL [https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple](https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple)? Using standard content negotiation (Language and MIME type)?

Ah, I see now. No, it’s not possible, but nice idea for improvement. How would you suggest to have it?

> [https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple&languageCode=pl-PL&mimetype=ttl](https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple&languageCode=pl-PL&mimetype=ttl)

or even:

> [https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple/ttl/pl](https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple/ttl/pl)

?

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 5, 2023, 3:03pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/14 "2023-04-05T15:03:15Z")

</div>

> standard country-language codes from ISO, can you explain what is the problem with them?

Citing [RFC 5646: Tags for Identifying Languages](https://www.rfc-editor.org/rfc/rfc5646.html#section-2.2.4)

> Region subtags are used to indicate linguistic variations associated  
> with or appropriate to a specific country, territory, or region.  
> Typically, a region subtag is used to indicate variations such as  
> regional dialects or usage, or region-specific spelling conventions.

“Polish as spoken in Poland” is just Polish, so adding the region subtag is not right.  
(Similarly, I tried to convince VIAF that tagging person authority names with `@it-VA` just because they came from Biblioteca Vaticana is wrong, because pure `@it` is spoken in the Vatican).

> How would you suggest to have it?

Please read [Cool URIs for the Semantic Web](https://www.w3.org/TR/cooluris) and [Hypertext Style: Cool URIs don't change.](https://www.w3.org/Provider/Style/URI).  
URIs (or their better brother resolvable URLs) are identifiers of things. They shouldn’t reflect implementation or representation details.

Then read [Content negotiation - Wikipedia](https://en.wikipedia.org/wiki/Content_negotiation). HTTP uses standard headers ([List of HTTP header fields - Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields)), so you don’t need to mangle the URL.

- the client uses `Accept-Language:` and `Accept:`
- the server uses `Language:` and `Content-Type`

Eg this asks for the classification as Turtle; in Polish or as fallback in English or German:

```auto
curl -L -Haccept-language:pl,en,de -Haccept:text/turtle \
 https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple

```

The “fallback” should be used for every translatable field individually.  
I.e. you should not duplicate strings in entity language variants.

More importantly, you should not duplicate non-translatable data.  
There must be **only one** semantic URL [https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple](https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple) that knows its name and description in a variety of languages. If you duplicate data, that makes it very hard to maintain.

Most importantly, the semantic URL should not depend on language. If you have `https:.../apple/en` vs `https:.../apple/pl`, that means that an English AECO company cannot interoperate easily with a Polish company because they use different URLs (identifiers) for the same thing.

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 11, 2023, 12:08pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/15 "2023-04-11T12:08:52Z")

</div>

Thanks for the sources. At first, I didn’t fully understand you, but now I think I do. What you described with one URL is how bSDD currently works, so glad you agree with it. The MIME type can be specified in REST API with the header, but the languageCode must be a parameter. For example you can request:

```auto
curl -X 'GET' \
 'https://test.bsdd.buildingsmart.org/api/Classification/v4?namespaceUri=https%3A%2F%2Fidentifier.buildingsmart.org%2Furi%2Fbs-agri%2Ffruitvegs-1.0%2Fclass%2Fapple&languageCode=pl-PL' \
 -H 'accept: text/turtle'

```

Is that solution meeting your expectations?

Regarding how the data is stored, we only keep translations on top of the core data in its original language, without duplicating non-translatable parts.

---

<div class="post-metadata">

**Author:** ![VladimirAlexiev](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/vladimiralexiev/32/2065_2.png) [@VladimirAlexiev](https://forums.buildingsmart.org/u/VladimirAlexiev)\
**Post date:** [April 19, 2023, 6:37am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/16 "2023-04-19T06:37:46Z")

</div>

Hi @artur_tomczak! This still doesn’t follow the Web Architecture principles about resource (entity/semantic) URLs.  
Eg to fetch the classification “apple” in Polish (or English, or German) in Turtle, one should be able to use:

```auto
curl -L -Haccept-language:pl,en,de -Haccept:text/turtle \
  https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple

```

See [4.6.3. Use Language Content Negotiation](https://bsdd.ontotext.com/README.html#orgb1a379a), and more details in its parent section [4.6. Improve Multilingual Support](https://bsdd.ontotext.com/README.html#improve-multilingual-support)

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 19, 2023, 8:47am UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/17 "2023-04-19T08:47:37Z")

</div>

Thank you for the explanation @VladimirAlexiev, makes sense. We added to our backlog to improve that.

---

<div class="post-metadata">

**Author:** ![artur\_tomczak](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/artur_tomczak/32/2632_2.png) [@artur\_tomczak](https://forums.buildingsmart.org/u/artur_tomczak)\
**Post date:** [April 26, 2023, 3:16pm UTC](https://forums.buildingsmart.org/t/proper-way-to-access-translations-of-ifc-entities/4092/18 "2023-04-26T15:16:21Z")

</div>

As discussed on the meeting today, the language header is working, but there are two problems in the above query:

- the “pl” is not recognized, as we use “pl-PL” in bSDD. We will add support for “pl” as well.
- if something is not in the Production server, it doesn’t have the “/identifier.buildingsmart” assigned. You could use the “test.bsdd” instead, for example “[https://test.bsdd.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple](https://test.bsdd.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple)”, but this just for testing.

So a query that works now and gives you content in Polish could be:

> curl -L -Haccept-language:pl-PL [https://test.bsdd.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple](https://test.bsdd.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple)