New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add explanation how an Excel file for list creation must be structured (DEV-533) #159
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
f3fad29
explanation how to structure an excel list for dsp-tools excel command
jnussbaum f803998
add reviewer's feedback
jnussbaum 77d7fea
Merge branch 'main' into wip/dev-533-add-excel_to_json_list-to-docs
jnussbaum af4acaf
improve the "Complete example":
jnussbaum File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -74,72 +74,82 @@ For further information about properties, see [here](./dsp-tools-create-ontologi | |||||
|
||||||
[not yet implemented] | ||||||
|
||||||
|
||||||
|
||||||
|
||||||
|
||||||
## Create a list from one or several Excel files | ||||||
|
||||||
With dsp-tools, a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON | ||||||
ontology and uploaded to a DSP server. It is possible to create multilingual lists. In this case, a separate | ||||||
Excel file has to be created for each language. The data must be in the first worksheet of each Excel file. | ||||||
It is important that all the Excel lists have the same structure. So, the translation of a label in one Excel | ||||||
sheet has to be in the exact same cell than the original was in the other Excel sheet (i.e. same cell index). | ||||||
|
||||||
**It is recommended to work from the following templates: | ||||||
[description_en.xlsx](assets/templates/description_en.xlsx): The English list "description" | ||||||
[Beschreibung_de.xlsx](assets/templates/Beschreibung_de.xlsx): Its German counterpart "Beschreibung"** | ||||||
|
||||||
With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON | ||||||
ontology and uploaded to a DSP server. The expected structure of the Excel files is described | ||||||
[here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a separate | ||||||
Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). | ||||||
It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel | ||||||
sheet has to be in the exact same cell (i.e. with the same cell index) in its own Excel sheet. | ||||||
The Excel sheets must have the following structure: | ||||||
![img-list-english-example.png](assets/images/img-list-english-example.png) | ||||||
![img-list-german-example.png](assets/images/img-list-german-example.png) | ||||||
|
||||||
Only Excel files with file extension `.xlsx` are considered. All Excel files have to be located in the same directory. | ||||||
When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has | ||||||
to be provided in the Excel file's file name after an underline and before the file extension, p.ex. `liste_de.xlsx` | ||||||
would be considered a list with German (`de`) labels, `list_en.xlsx` a list with English (`en`) labels. The language | ||||||
has to be a valid ISO 639-1 or ISO 639-2 language code. | ||||||
to be provided in the Excel file's file name after an underline and before the file extension, e.g. | ||||||
`Beschreibung_de.xlsx` would be considered a list with German (`de`) labels, `description_en.xlsx` a list with | ||||||
English (`en`) labels. The language has to be one of {de, en, fr, it}. | ||||||
|
||||||
The following example shows how to create a JSON list from two Excel files which are in a directory called `lists`. | ||||||
The following example shows how to create a JSON list from two Excel files which are in a directory called `listfolder`. | ||||||
The output is written to the file `list.json`. | ||||||
|
||||||
```bash | ||||||
dsp-tools excel lists list.json | ||||||
dsp-tools excel listfolder list.json | ||||||
``` | ||||||
|
||||||
The two Excel files `liste_de.xlsx` and `list_en.xlsx` are located in a folder called `lists`. `liste_de.xlsx` | ||||||
contains German labels for the list, `list_en.xlsx` contains the English labels. | ||||||
The two Excel files `Beschreibung_de.xlsx` and `description_en.xlsx` are located in a folder called `listfolder`. | ||||||
|
||||||
``` | ||||||
lists | ||||||
|__ liste_de.xlsx | ||||||
|__ list_en.xlsx | ||||||
listfolder | ||||||
|__ Beschreibung_de.xlsx | ||||||
|__ description_en.xlsx | ||||||
``` | ||||||
|
||||||
For each list node, the `label`s are read from the Excel files. The language code, provided in the file name, is then | ||||||
used for the labels. As node `name`, a simplified version of the English label is taken if English is one of the | ||||||
For each list node, the labels are read from the Excel files. The language code, provided in the file name, is then | ||||||
used for the labels. As node name, a simplified version of the English label is taken if English is one of the | ||||||
available languages. If English is not available, one of the other languages is chosen (which one depends on the | ||||||
representation of the file order). If there are two node names with the same name, an incrementing number is appended to | ||||||
the `name`. | ||||||
|
||||||
```JSON | ||||||
{ | ||||||
"name": "sand", | ||||||
"name": "description", | ||||||
"labels": { | ||||||
"de": "Sand", | ||||||
"en": "sand" | ||||||
"de": "Beschreibung", | ||||||
"en": "description" | ||||||
}, | ||||||
"nodes": [ | ||||||
{ | ||||||
"name": "fine-sand", | ||||||
"labels": { | ||||||
"de": "Feinsand", | ||||||
"en": "fine sand" | ||||||
} | ||||||
}, | ||||||
{ | ||||||
"name": "medium-sand", | ||||||
"labels": { | ||||||
"de": "Mittelsand", | ||||||
"en": "medium sand" | ||||||
} | ||||||
}, | ||||||
{ | ||||||
"name": "coarse-sand", | ||||||
"name": "first-sublist", | ||||||
"labels": { | ||||||
"de": "Grobsand", | ||||||
"en": "coarse sand" | ||||||
} | ||||||
"de": "erste Unterliste", | ||||||
"en": "first sublist" | ||||||
}, | ||||||
"nodes": [ | ||||||
{ | ||||||
"name": "first-subnode", | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
"labels": { | ||||||
"de": "erster Listenknoten", | ||||||
"en": "first subnode" | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
}, | ||||||
"nodes": [ | ||||||
{ | ||||||
... | ||||||
} | ||||||
] | ||||||
}, | ||||||
... | ||||||
] | ||||||
} | ||||||
] | ||||||
} | ||||||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In my view, it is confusing to use the term "sub-list". The node called "first-sublist" here is the actual list. I would suggest using "list" or "my-list" or something similar.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As I understand, the contents of Excel column A are already nodes/sublists. The top-level list name is defined by the file name.
In every case, my test data behaves that way...