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:


 * 1) Backward compatibility considerations:
 * 2) * The new language fields are optional.
 * 3) * ISFDB should work with the old database content as before without a data migration.
 * 4) * 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.
 * 5) Users will be able to select the languages that they are interested in via User Preferences - already implemented
 * 6) Author records will have two optional fields added. The fields will store the author's "working languages".
 * 7) Title records will have a new optional field added. The field will store the primary language of the title.
 * 8) The Award page will display all awards regardless of the language. Note that this functionality may be revisited when award support is improved.
 * 9) 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:
 * 10) * Canonical titles are always displayed regardless of user preferences
 * 11) * If the language field is not populated for a given VT, then it will be displayed.
 * 12) * If the user is not signed in, then the Bibliography pages will only display canonical titles and English VT translations.
 * 13) * 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.
 * 14) 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:
 * 15) * The new option will prompt the user to enter the following fields: Title, Year, Note, Language, Translator(s)
 * 16) * 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
 * 17) * The title of the VT record will not be defaulted and the user will have to enter it
 * 18) * The user will be able to enter one or more optional translators
 * 19) * The user will be able to select the language of the VT
 * 20) * 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)
 * 21) * 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
 * 22) In case of editing translations the same limitations will apply as described above for adding translations - needs to be discussed
 * 23) Translations can be deleted the same way as any other variant titles
 * 24) Author summary pages will only display canonical collection and omnibus titles in the following cases:
 * 25) * the language of the canonical title is undefined
 * 26) * the language of the canonical title is one of the authors' "working languages"
 * 27) * the language of the canonical title is one of the current user's preferred languages
 * 28) * the current user's User Preferences are set to display all languages
 * 29) Users will be able to search for titles translated to the most languages
 * 30) Translations of reviews and interviews are out of scope
 * 31) 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
 * 32) The same procedure should work for Short Fiction titles
 * 33) 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

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
 * SQLreadLanguageName
 * SQLgetLanguageId
 * SQLTitleTranslators
 * SQLisDisplayAllLanguages
 * SQLloadUserLanguages
 * 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
 * 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