Template:bg-ndecl/documentation

Introduction
This template should be used to decline all Bulgarian nouns, in preference to any other, older template that may still exist. (Eventually these will all be eliminated.)

Generally, a single argument is supplied to the template, consisting of a noun (multisyllabic nouns are required to have an acute accent indicating the stress) followed by a declension spec in angle brackets. In the most basic case, nothing needs to be supplied between the angle brackets. For example, for the noun :

produces

Indicators
Indicators can be specified inside of angle brackets to modify the default declension behavior. For example, the  indicator specifies that the noun has a vocative, which is generated according to the normal rules documented in  on Wikipedia. An example is the noun :

produces

Another indicator is, which indicates that the noun is "reducible" in its plural form (i.e. an е or ъ in the last syllable drops out in the plural). For example, for the noun :

produces

Multiple indicators can be combined by simply concatenating them (in any order), for example for the noun :

produces

Note here that the module automatically knows that if the final е to be dropped out is preceded by a vowel, й must be inserted.

Default and explicit plurals
All of the above examples have been of multisyllabic masculine nouns, where the default plural is -и. This is also the default for all feminine nouns, but monosyllabic masculine nouns default to -ове, for example :

produces

Some monosyllabic nouns have a plural in -и or otherwise have an irregular plural. This can be indicated by supplying the plural after a  sign. For example, is monosyllabic but has a plural in -и:

produces

Multiple plurals can be specified, e.g. for :

produces

The plural ending -и automatically causes the to be applied, i.e. final к -> ц, and similarly г -> з and х -> с. For example, has the normal plural ези́ци:

produces

Some nouns are exceptional and do not undergo this change, which can be indicated using, e.g. for , plural ква́рки:

produces

Note also that the above change applies only to masculine nouns ending in a consonant. Nouns ending in an -а (most feminine nouns, as well as some masculine nouns) such do not undergo this change, e.g., plural кни́ги:

produces

Stress patterns
Some nouns, especially but not limited to monosyllabic masculine nouns, have a stress shift in the definite singular and/or plural. This can be specified using a stress pattern indicator, which is one of,  ,   or  :

For example, has definite singular гласъ́т, plural гласове́:

produces

Some nouns have different multiple possible stress patterns, which can be indicated by concatenating the stress pattern indicators, for example has definite singular сълза́та (stem-stressed) and plural either съ́лзи (stem-stressed) or сълзи́ (ending-stressed), hence it can follow either pattern   or  :

produces

Another way to handle cases where the plural ending is stressed is to add an accent mark to an explicitly specified plural ending, e.g for with plurals е́кове or екове́:

produces

The general rule is that if no accent mark is present, an accent mark will automatically be added if called for by the stress pattern, but an explicit accent mark overrides any stress pattern. As an example, another way to write (see above) is as follows:

which produces

Here, we specify both an unstressed plural ending -и and a stressed plural ending -и́. In this case, we have to explicitly indicate that the stress pattern is, because the default for feminines and neuters whose lemma has ending stress is  , which will automatically add a stress to the unstressed   specification.

Specifically, the following rules are used to determine the default stress pattern:
 * Nouns ending in -а́, -я́, -е́ and -о́ (regardless of gender) default to  (i.e. the plural will also be ending-stressed).
 * Masculine reducible nouns (those with the indicator ) where the reducible vowel is stressed default to , e.g. , plural чужденци́.
 * Feminine nouns ending in a consonant (these require the  indicator, see below) default to , e.g. , definite singular , plural.
 * All other nouns default to.

Stems and endings
The above discussion of adding the plural ending -и to glossed over the fact that the ending is not added directly to the lemma сълза́ but to the stem съ́лз-. The stem is used when adding plural and other endings, and is generated from the lemma as follows: Finally, if the resulting stem has no accent, an accent is added to the last vowel, so that e.g. the stem of is бряг- the stem of  is же́н-, and the stem of  is госпо́ж-. (In the latter case, for example, specifying will correctly generate plural госпо́жи.)
 * If the noun ends in -а, -я, -е or -о (stressed or not), this is removed and the remainder becomes the stem.
 * Otherwise, if the noun begins with a capital letter and ends in -и (stressed or not), as in the name but not the words  or {m|bg|цуна́ми||tsunami}}, the -и is removed and the remainder becomes the stem.
 * If the noun ends in -й, e.g. or, this is removed and the remainder becomes the stem.
 * Otherwise, the whole lemma is the stem.

Default and explicit gender indications
Examples were given above of masculine and feminine nouns. In general, the module needs to know the gender of a noun in order to properly decline it. Most of the time, the gender can be automatically determined from the ending, as follows: There are some exceptions, which should be indicated using a gender indicator, one of,   or  , for example , which is feminine:
 * 1) Nouns ending in a consonant are by default masculine.
 * 2) Nouns ending in -а or -я (stressed or not) are by default feminine.
 * 3) All other nouns are by default neuter.

produces

Note that when the module knows that this is a feminine noun, it automatically uses the definite singular ending -та instead of -ът and plural -и instead of -ове (the default for monosyllabic masculine nouns), and automatically defaults to stress pattern, so that the definite singular ending -та is stressed, as in all feminine nouns ending in a consonant.

Overriding plurals, vocatives, etc.
Some nouns have more complex plurals than can be easily indicated using the  format, or have other irregularities, as follows, for :

which produces

Here the general format is a slash, followed by a property name and one or more colon-separated values. In this case, we explicitly specify an irregular plural хо́ра and irregular vocative чове́че. (The definite plural хо́рата does not explicitly need to be given; it is generated according to a regular rule.)

Multiple overriding values can be given, e.g.:

which produces

Here,  is a shortcut for whatever value(s) would normally be generated according to the default rules. In this case, the normal plural of is чове́ци, so specifying   is equivalent to specifying   explicitly. So the effect is to specify three plurals: хо́ра, чове́ци and лю́де. (The latter two are archaic; the next section describes how to indicate this using a footnote.)

You can also use  as a shortcut for the lemma (so that e.g   generates a value by adding и to the lemma), and   (the indefinite plural, from which the definite plural is automatically generated)
 * (the definite subjective singular, from which the definite objective singular is automatically generated)
 * (the count form)
 * (the vocative singular form; if you specify this, you do not have to specify  to get the vocative to display)
 * (the dative singular form, for nouns that have this form)
 * (the genitive singular form, for nouns that have this form)
 * (the accusative singular form, for nouns that have this form)
 * (the dative plural form, for nouns that have this form)
 * (the genitive plural form, for nouns that have this form)
 * (the accusative plural form, for nouns that have this form)

The following special property names are also recognized:


 * ,  (specify that this is a singulare tantum [singular only] or plurale tantum [plural only] noun)
 * (specify that the noun has no definite singular; this is the default for nouns beginning with a capital letter, and to get the definite singular to display for these nouns you must specify )
 * (specify that the noun has no plural; this is primarily useful for those few nouns that have no plural but do have a count form, such as ; for singular-only nouns, use  )
 * (specify that the noun has no definite plural)
 * (specify that the noun has no count form)

For example, to specify the declension of plurale tantum noun, use:

which produces

To specify the declension of, which has a vocative гла́во and archaic genitive plural глав, use:

which produces

(See the next section for footnote annotations such as .)

Stem alternations
In nouns with stressed -я́-, the -я́- automatically converts to -е- when a stressed ending is added, for example,, definite singular , plural (but count form ):
 * -я- vs. -е-

produces

In some nouns, this change also happens when an unstressed ending beginning with -е or -и is added. This can be signaled using the  indicator, as with  plural ме́рки:

produces

Conversely, in a few nouns, the change -я́- -> -е- does not happen even when a stressed ending is added; this can be signaled using, as with  plural одеяла́ (stress pattern  , see above):

produces

Another stem alternation that occurs in some nouns is a change from -ръ- to -ър- before endings beginning with a vowel. For example, has definite singular гърбъ́т, plural гърбове́, etc. This can be specified using the   indicator:
 * -ръ- vs. -ър-

produces

This change occurs only before endings beginning with a vowel. For example, the feminine noun has plural къ́рви (with the change) but definite singular кръвта́ (without the change).

This indicator is not the default for any nouns because only some nouns in -ръ- have this change.

Palatalized endings
Some masculine nouns unexpectedly have definite singular in -ят instead of -ът, and the count form in -я instead of -а. This can be specified using the indicator, e.g. for :

which produces

Some masculine nouns automatically act as if  were specified: For such nouns, you can disable the  behavior using. An example noun that needs this is, with definite subjective singular ку́фарът:
 * 1) nouns ending in a vowel + -тел, e.g. ;
 * 2) nouns ending in a vowel + consonant + -ар, e.g. ;
 * 3) nouns ending in -й, e.g..

which produces

Alternative stresses
Some nouns can be stressed in more than one place, e.g., also stressed as. To indicate this, use the following syntax:

which produces

The general form is to specify two or more comma-separated sets of lemma + spec, surrounded by double parentheses. There is no requirement that the different sets have the same specs. For example, has an alternative stress pattern, but in all cases the plural is вина́ (referring to different types of wines). This can be indicated as follows:

which produces

Adjectival nouns
Some nouns are derived from adjectives and declined like them. An example is, derived from ; it is literally "military man". As an adjectival noun, it has definite subjective singular вое́нният instead of *вое́ннът, as would be expected for a regular noun. To indicate this, use the  indicator. Along with this, you can use other adjectival indicators as documented in. In addition, you can use the following:
 * to indicate that the noun has a vocative;
 * to indicate that the noun is a male human (currently synonymous with );
 * or  to indicate that the noun is singular-only or plural-only.

For example, to decline the adjectival noun, use the following syntax:

which produces

As another example, to decline the adjectival noun, use the following syntax:

which produces

Multiword expressions
Multiword expressions are supported. For example, to decline the noun, use the following syntax:

which produces

Note how the adjective is marked with, as for adjectival nouns (see above). The module automatically knows that in adjective-noun combinations, only the first adjective receives definite endings.

You can insert links into the declension syntax, and they will automatically be removed when declining the noun. For example, equivalent to the above is the following:

which produces

These links are especially useful in, which can take the same syntax as ; the links will properly go into the headword.

Another example, for :

produces

Here, the adjective is reducible and the overall expression is singular-only. Note that the singular-only code  only needs to be indicated once (preferably on the noun).

The reducible code  only needs to be indicated on masculine singular adjectives. Other reducible adjectives are always in reduced form, and will work fine with or without the  reducible indicator, for example, for :

produces

You can include more than two words. For example, for the noun, use the following syntax:

which produces

Here, only the first adjective receives definite markings, as is correct.

A slightly more complex example is :

which produces

Here, there is an alternation between я and е in the adjective, which needs to be indicated by, and  can take two possible stresses in the plural. Note that both plural forms are correctly generated and attached to the appropriate adjective form.

Another complex example is :

which produces

This shows that all the indicators and overrides normally available for a noun can still be used here, and will work correctly. In this case, the explicit vocative override causes the overall expression to have a vocative, and the fact that the adjective has two possible vocative forms means the overall expression will also have two possible vocatives.

Arbitrary text can be included between or around declined words, for example for :

produces

Here, the word is undeclined, and is included as-is in all forms.

Alternants and other complexities can be included and work fine. For example, if we wanted to generate the declension of (also stressable as,  or ), we would use the following:

which produces

Parameters
The general format is as follows: . More specifically:
 * 1) There can be zero or more stress pattern codes at the beginning. The allowed codes are
 * = stem-stressed in both def sg and plural
 * = ending-stressed in both def sg and plural
 * = stem-stressed in def sg, ending-stressed in plural
 * = ending-stressed in def sg, stem-stressed in plural
 * Note that the interpretation of these is a bit different from the Russian equivalents.
 * The defaults are as follows:
 * 1) Masculine nouns with reducible plural where the stress is on the reducible vowel (e.g. чуждене́ц, def sg. чуждене́цът, pl. чужденци́) default to  ; others default to.
 * 2) Feminine nouns ending in stressed -а́ or -я́ (e.g. жена́, def sg. жена́та pl. жени́) default to  ; feminine nouns ending in a consonant (e.g. нощ def sg. нощта́, pl. но́щи) default to  ; others default to.
 * 3) Neuter nouns ending in stressed -о́ or -е́ default to  ; others default to.
 * 4) Following the stress pattern codes are zero or more indicators, which are mostly inside of parens:
 * (indicates reducible plural)
 * (indicates reducible def sg)
 * (indicates reducible vocative)
 * (indicates reducible count form)
 * (indicates that the noun has a vocative)
 * (indicates that the def sg is in -ят/-я and the count is in -я, instead of def sg -ът/-а and count in -а; automatically inferred for nouns ending in -й, vowel + -тел or vowel + -ар)
 * (prevents  from being inferred when it normally would be)
 * (indicates ръ -> ър change when a vowel-initial ending is added)
 * (indicates я́ -> е́ when an ending beginning with -е, -и or -ь is added; note that the change я́ -> unstressed е is automatic when a stressed ending is added, unless  is given)
 * (prevents the normally automatic change я́ -> unstressed е when a stressed ending is added, e.g. in plural )
 * (indicates that -ин is lost in the plural)
 * (indicates unpredictably masculine, e.g. when ending in a vowel)
 * (indicates unpredictably feminine, e.g. when ending in consonant)
 * (indicates unpredictably neuter)
 * 1) Following this are zero or more plural specs, e.g. ,  ,  .   normally causes palatalization of word-final к, г, х (except for word-final нг) -> ци, зи, си;   similarly causes palatalization of word-final ка, га, ха -> це, зе, се. To disable this, use   or.
 * 2) Following this is zero or more property specs. Currently recognized properties are:
 * (specify the indefinite plural form)
 * (specify the definite singular subjective form)
 * (specify the count form)
 * (specify the vocative form)
 * (restrict the noun to singular-only or plural-only).
 * All the properties specifying particular forms should be followed by one or more colon-separated forms, where the special value  means "use the default form" and   and   or  . Certain abbreviations are recognized for the footnotes, e.g.
 * These abbreviations are also recognized inside of angle brackets, which allows you to specify other text in addition; for example,  = ,   =  , etc.
 * Note that specifying a plural form using a property spec overrides any plurals specified using  or similar, so only one of the two mechanisms should be used.
 * 1) Finally, more than one of the entire specification (including the initial specs, plurals and properties) can be given, comma-separated.
 * These abbreviations are also recognized inside of angle brackets, which allows you to specify other text in addition; for example,  = ,   =  , etc.
 * Note that specifying a plural form using a property spec overrides any plurals specified using  or similar, so only one of the two mechanisms should be used.
 * 1) Finally, more than one of the entire specification (including the initial specs, plurals and properties) can be given, comma-separated.
 * These abbreviations are also recognized inside of angle brackets, which allows you to specify other text in addition; for example,  = ,   =  , etc.
 * Note that specifying a plural form using a property spec overrides any plurals specified using  or similar, so only one of the two mechanisms should be used.
 * 1) Finally, more than one of the entire specification (including the initial specs, plurals and properties) can be given, comma-separated.
 * These abbreviations are also recognized inside of angle brackets, which allows you to specify other text in addition; for example,  = ,   =  , etc.
 * Note that specifying a plural form using a property spec overrides any plurals specified using  or similar, so only one of the two mechanisms should be used.
 * 1) Finally, more than one of the entire specification (including the initial specs, plurals and properties) can be given, comma-separated.

Properties and manual overrides
The following overrides are recognized for nouns:
 * (specify the indefinite plural form, from which the definite plural form is automatically constructed)
 * (specify the indefinite plural form only)
 * (specify the definite plural form only)
 * (specify the definite singular subjective form, from which the definite singular objective form is automatically constructed)
 * (specify the definite singular subjective form only)
 * (specify the definite singular objective form only)
 * (specify the indefinite singular form only; this is the lemma form, and an override here can be useful if the lemma is irregular compared with other forms)
 * (specify the count form)
 * (specify the vocative singular form)
 * (specify the accusative singular form)
 * (specify the genitive singular form)
 * (specify the dative singular form)
 * (specify the accusative plural form)
 * (specify the genitive plural form)
 * (specify the dative plural form)
 * (restrict the noun to singular-only or plural-only).

Combining stems and endings
Endings are normally added onto a stem. The formation of the stem from the lemma is described above. Once the stem is determined, the ending is added as follows:
 * 1) If the   indicator is specified and the ending begins with a vowel, the sequence CърC is replaced with CръC (preserving the stress as appropriate).
 * 2) If -я́- occurs, it is converted to -е́- under the following circumstances:
 * 3) the   indicator is not given; and either
 * 4) the ending is accented, or
 * 5) the   indicator is given and the ending begins with -е, -и or -ь.
 * 6) If the ending is accented, remove any stress from the stem.

Note the behavior of stressed -я́- in the stem:
 * 1) -я́- occurs, no indicator is given, and the ending is stressed: change to -е-. E.g. for : брегъ́т "the coast".
 * 2) -я́- occurs, no indicator is given, and the ending is unstressed: no change. E.g. for : два бря́га "two coasts".
 * 3) -я́- occurs,   is given, and the ending begins with е-, и- or ь-: change to -е́-. E.g. for : ме́рки "criteria".
 * 4) -я́- occurs,   is given, and the ending begins with a consonant or a vowel other than е-, и- or ь-: no change.
 * 5) -я́- occurs and   is given: no change even if the ending is stressed. E.g. for : одеяла́ "blankets".

Plural formation
The default rules for determining the plural ending are as follows:
 * 1) All feminine nouns default to.
 * 2) Masculine nouns form the plural as follows:
 * 3) For proper nouns (those beginning with an uppercase letter):
 * 4) If the word ends in -и (e.g. ), -я (e.g. ) or -й (e.g. ), the default is.
 * 5) Otherwise, if the word ends in -ов (e.g. /) or -ев (e.g. ), the default is   (i.e. two default plurals).
 * 6) Otherwise (e.g., , , ), the default is.
 * 7) For common nouns (those beginning with a lowercase letter):
 * 8) If the word ends in -о (stressed or unstressed, e.g., ) or stressed -а́н (e.g. ), the default is.
 * 9) Otherwise, if the word ends in -е (e.g. ), the default is.
 * 10) Otherwise, if the word is multisyllabic (e.g., , , , , etc.), the default is.
 * 11) Otherwise, if the word ends in -й (e.g., ), the default is.
 * 12) Other monosyllabic nouns for which   is specified (e.g., , ) default to.
 * 13) All remaining monosyllabic nouns default to.
 * 14) Neuter nouns form the plural as follows:
 * 15) If the word ends in -о, -ще or -це, the default is.
 * 16) If the word ends in -ие, the default is.
 * 17) For other words ending in -е, the default is  . (Note that the plural ending is added onto the stem, not the lemma, hence the plural of  is носле́та, i.e. stem но́сл- + -е́та.)
 * 18) Any remaining words (primarily loanwords such as, , , ) default to  . (Note that for these words, the stem and lemma are the same, hence the plural of  is такси́та.)

Once the plural ending is determined or specified, it may need a stress mark added (specifically if the stres pattern is  or   and no stress mark is explicitly given). If so, it is added as follows:
 * 1) -еса́ and -ена́ are stressed as shown.
 * 2) -ове́, -ьове́, -йове́ and -еве́ are stressed as shown if the stress pattern is   (but not  ).
 * 3) All other plurals are stressed on the first vowel.

After this, the stem to add the plural to needs to be determined. The normal rules for determining the stem from the lemma are described above, but in addition:
 * 1) If the   is specified, or if it is inferred (this happens for nouns in -зъм, such as ), the stem is "reduced" by deleting -е- or -ъ- before a single final consonant. (If the noun does not have this form, an error is signaled.)
 * 2) If the   indicator was specified (e.g. for words like, ), final -ин is removed. If the resulting stem has no stress, it is added onto the last syllable.
 * 3) If the plural to be added is   (but not  ), and the lemma ends in -к, -г or -х (e.g., plural ези́ци) and does not end in -нг (e.g. , , with plurals ми́тинги, ло́зунги), the  is applied to the final consonant, i.e. final к -> ц, final г -> з and final х -> с.
 * 4) The Slavic second palatalization is also applied if the plural to be added is   (but not  ) and the lemma ends in -ка, -га or -ха (e.g., plural ръце́).

Finally, the plural ending is added onto the stem according to the rules described above (which an accent from the stem if present in the ending, and may modify the stem if it contains -ръ- or stressed -я́-).

Vocative formation
The default rules for forming the vocative are as described in the Wikipedia entry on : Note that the added ending never bears the stress, regardless of the stress pattern.
 * 1) Neuter nouns, feminine nouns ending in a consonant, and nouns for which none of ,   and   are specified have no default vocative.
 * 2) Nouns for which   is specified or inferred (i.e. nouns in -ар, -тел or -й, unless   is given) add -ю to the stem.
 * 3) Nouns ending in a vowel + -я add -йо to the stem.
 * 4) Nouns ending in a consonant + -я add -ьо to the stem.
 * 5) Nouns ending in -ца, -рка or -чка, as well as all proper nouns ending in -ка, add -е to the stem.
 * 6) All other nouns in -а add -о to the stem.
 * 7) Nouns ending in -к, -ч, -ц or -ин add -о.
 * 8) Nouns ending in -г or -з change this final consonant to -ж and add -е.
 * 9) All other nouns (i.e. masculine nouns ending in a consonant, other than those mentioned above) add -е.

Count form formation
The default rules for forming the count form are as follows: Note that the added ending never bears the stress, regardless of the stress pattern.
 * 1) Nouns that aren't masculine or don't end in a consonant have no default count form.
 * 2) Nouns for which   is specified or inferred (i.e. nouns in -ар, -тел or -й, unless   is given) add -я to the stem.
 * 3) Other nouns add -а.