Requirements:Translations

This page is intended to be a clean specification for the support of creating/editing/displaying translations. Discussions about the data here should be entered on the discussion page.

Description of the current situation

At this time ISFDB has limited support for translations. The limitations are as follows:

English is currently the privileged language in ISFDB. Foreign language translations of English language books do not get their own title records; they are entered as Publications under the canonical English language title.
If a title was originally written in a foreign language, the canonical title is the title of the work as it appeared in that language. If one or more English language translations of the title have been published, they are entered as Variant Titles. If a literal English translation of the title is known, it is documented in Notes.
If a book was written in English, but a foreign language translation was published first, then the English language title is entered as the canonical title.
Translators of translated works can only be added in publication level notes.
Original foreign language collections and omnibuses of English language authors' works (i.e. books which have no analog in English) can be entered as canonical titles. The added title is then displayed on the author's Summary Bibliography page mixed with English collections and omnibuses.
Translations of Short Fiction, Poem and Essay titles into languages other than English are not supported by ISFDB.

Requirements specification

The translation support enhancement should fulfill the following requirements:

Backward compatibility considerations:
- The new language fields are optional.
- ISFDB should work with the old database content as before without a data migration.
- The conversion of currently existing foreign language translations entered as publications is outside of the scope of this project and will be performed at a later point.
Users will be able to select the languages that they are interested in via User Preferences - already implemented
Author records will have two optional fields added. The fields will store the author's "working languages".
Title records will have a new optional field added. The field will store the primary language of the title.
The Award page will display all awards regardless of the language. Note that this functionality may be revisited when award support is improved.
Other author-specific bibliography pages (i.e. the Summary, Chronological and Alphabetical pages) will display only the VTs whose languages are stored in the current user's User Preferences. The desired behavior is as follows:
- Canonical titles are always displayed regardless of user preferences
- If the language field is not populated for a given VT, then it will be displayed.
- If the user is not signed in, then the Bibliography pages will only display canonical titles and English VT translations.
- If the current user's User Preferences are set to display all languages, then all VTS will be displayed regardless of the VT's language.
Users will have access to a new option to add a translated title to a canonical title record as a variant title (VT). The option will behave as follows:
- The new option will prompt the user to enter the following fields: Title, Year, Note, Language, Translator(s)
- The author(s) of the VT will default to the author(s) of the canonical title. The user will be able to view this data, but will not be able to modify it
- The title of the VT record will not be defaulted and the user will have to enter it
- The user will be able to enter one or more optional translators
- The user will be able to select the language of the VT
- The user will not be able to select the language of the canonical title as the language of the VT (only applicable if the canonical title has a language specified)
- The title type and the story length fields of the VT record will be defaulted based on the data in the respective canonical title fields and will not be editable
In case of editing translations the same limitations will apply as described above for adding translations - needs to be discussed
Translations can be deleted the same way as any other variant titles
Author summary pages will only display canonical collection and omnibus titles in the following cases:
- the language of the canonical title is undefined
- the language of the canonical title is one of the authors' "working languages"
- the language of the canonical title is one of the current user's preferred languages
- the current user's User Preferences are set to display all languages
Users will be able to search for titles translated to the most languages
Translations of reviews and interviews are out of scope
Existing translation record (stored as publications) can be migrated into new translations with the following steps: 1) Unmerge your translations 2) Create Variant Title of the original title from the unmerged title and 3) Set the language of the translation by editing the Variant Title 4) Set the translators by editing the Translations
The same procedure should work for Short Fiction titles
Support translations (by adding Language and Translator fields) in the Content section of publications

Database schema changes

The following database schema changes are required:

ALTER TABLE titles ADD title_language INT(11) DEFAULT NULL;
ALTER TABLE authors ADD author_language INT(11) DEFAULT NULL;
ALTER TABLE authors ADD author_language2 INT(11) DEFAULT NULL;

Note that some changes are already implemented in the database schema:

languages table added
user_languages table added
user_preferences table enhanced with display_all_languages field

UI mockups

Add "Add Translation to This Title" menu item to the navigation bar of the title screen

Author's summary page displaying VTs as translations (see REQ #6)

Note that the "Hungarian Translation" lines appear if and only if the user logged in and selected the "Hungarian" in his/her user preferences

New title overview for translations (translator added, original language and translation language added)

shortfiction example:

Title screen: translations listed in an own section

Author's screen: translation of the given author listed in an own section
Author's screen: omnibus list restricted to the "working languages" to the author
New "Add translation" screen (the yellow fields are read only)

Edit author data screen (extended by two language fields)

Edit title screen for translations (the yellow fields are read only)

Edit title screen for original titles and variant titles (extended by original language field)

New confirmation screen for add translation action

Updated confirmation screen for edit title action

Content section of publications extended by language and translator fields

Detailed design

biblio package

common.py
- add new menu item to the title page
- add displayTranslationTitle method to support translations on the summary, chronological, alphabetical, series pages.
- change displayVariants method to determine if a VT is translation or not and call displayTranslationTitle for translations
mylanguages.py
- call SQLisDisplayAllLanguages instead of direct db access
- call SQLloadUserLanguages instead of direct db access
submitmylanguages.py
- usage of the user_choice db flag to be corrected
  - update user_languages set user_choice = '%s' where user_lang_id = %d
title.sy
- add step2 - get the title's authors
  - display original language in the header
  - display original language and translation language in the header for translation
  - display "translation" instead of "varian title" in case of translation
- in step3 - collect translations and variant titles in different lists
- step6 - display translations
biblio.py
- add checkLanguage method to doublecheck if a collection or omnibus has to be displayed on the author's summary pages
- call checkLanguage from diplayWorks method

common package

authorClass.py
- add author_language and author_language2 (XML tags: AuthorLanguage and AuthorLanguage2)
isfdb.py
- add AUTHOR_LANGUAGE = 14 and AUTHOR_LANGUAGE2 = 15
- add TITLE_LANGUAGE = 16
- add MOD_TRANSLATION = 28 with long name "Translation"
- add DEFAULT_LANGUAGE = 'eng'
library.py
- add new PrintLangField2XML method
SQLparsing.py
- SQLloadLanguages
  - select lang_id,lang_name from languages order by lang_name
- SQLreadLanguageName
  - select lang_name from languages where lang_id = %d
- SQLgetLanguageId
  - select lang_id from languages where lang_code = '%s'
- SQLTitleTranslators
  - select authors.author_canonical from authors,canonical_author where authors.author_id=canonical_author.author_id and canonical_author.ca_status=4 and canonical_author.title_id='%d'
- SQLisDisplayAllLanguages
  - select display_all_languages from user_preferences where user_id='%d'
- SQLloadUserLanguages
  - select lang_id,user_choice from user_languages where user_id='%d'
titleClass.py
- add title_language
- add is_translation flag (calculated only from the db content, i.e. old or current title data)
- for translations: author array should be filled translators instead of authors
viewers.py
- DisplayAuthorChanges method: add Language and Language2 fields by calling PrintLangField2XML

edit package

addtranslation.py (new source file in the edit package, based on old addVariant.py)
- print Add Translation header
- query the given title from db
- display read only original title and editable translation title
- query authors and display them as read only fields
- add translators field and button
- add read only copyright year and editable translation year
- add read only original language and editable translation language (original language should be disabled in the drop down list of the translation language)
- display read only storylen and title type
- add empty note text area
editauth.py
- add Language drop down list - list of allowed values is read from languages table via SQLlistLanguages call - empty value allowed only for authors w/o author_language in the db for sake of backward compatibility, if you set the language then deleting is not allowed, only changing
- add Language2 drop down list - list of allowed values is read from languages table via SQLlistLanguages call - deleting second working language is always allowed
edittitle.py
- add SQLTitleTranslators method to query translators of the given title (translators are stored with ca_status = 4 in the canonical_author table
- add printReadOnlyField method to display yellow read only fields for translations
- determine if the title being edited is a translation (definion: translations have translators in the canonical_author table OR they have parent title and the parent title has a different language)
- for translations: display read only original title and editable translation title
- for translations: display read only authors and editable translators
- add language field (for original titles and translations as well)
- for translations: storylen and title type should be readonly
isfdblib.py
- addMetadataTitleTranslation script to be added based on addMetadataTitleAuthor
submitauth.py
- add Language and Language2
- if the Language and Language2 has the same value then only the Language is stored
- if Language is empty, but Language2 is filled out, then the value of the Language2 is stored in the Language instead of the Language2
submittitle.py
- support Translators tag instead of Authors tag in case of translations
- add Language field
submittranslation.py (new source file in the edit package)
- display Translation Submission title
- create XML message for submission including Title, TranslationYear, Language, TitleType, Storylen, Note, Authors, Translators XML tags
tv_merge.py
- support Language field in title merge
ts_merge_py
- support Language field in title merge

mod package

aa_update.py
- add AUTHOR_LANGUAGE and AUTHOR_LANGUAGE2 fields and convert their values from int to string
common.py
- add setTitleTranslators method
- support ca_status = 4 in the deleteTitleAuthor and addTitleAuthor methods
ta_update.py
- add Language field for titles
- add Translators by calling setTitleTranslators of common.py
tr_new.py (new source file)
- display Proposed Translation Submission title
- process Title, TranslationYear, Language, Note, Authors, Translators XML tags
tv_update.py
- add Language field
- remove old Translator field
- add new Translators fields if is_translation of the title class is set
va.new.py
- addTranslator method
- add support for Translation XML tag in addition to VariantTitle
- add Language field
- process Translators tag
tv_merge.py
- support Language field in title merge and original author is queried instead of translators if the VT is translation
ta_merge.py
- support Language field in title merge